Informações verificadas em
Webhook, callback ou polling: qual usar?
| Opção | Como funciona |
|---|---|
| Webhook | Cadastre um endpoint da conta para os eventos selecionados. |
| Callback | Envie callback_url na criação de uma operação específica. |
| Polling | Consulte estados e eventos periodicamente, sem endpoint de recebimento. |
Essas opções são independentes e podem coexistir. O mesmo evento pode chegar por webhook e callback; deduplique o processamento se ambos acionarem o mesmo fluxo.
Quais atualizações são enviadas?
operation.created e operation.updated acompanham operações criadas pela API. deposit.updated informa alterações observadas nos depósitos da conta após a ativação das integrações. webhook.test permite verificar a entrega sem movimentar saldo.
Não presuma que todos os pagamentos iniciados no site ou Telegram geram eventos de operação da API. Para conciliação da conta, combine os recursos documentados de operações, depósitos, saldo e extrato.
Como cadastrar e testar um webhook
Use uma chave com webhooks:write para cadastrar um destino HTTPS público com POST /webhooks. Armazene o segredo retornado; ele é necessário para validar a assinatura. Confira os campos e eventos na documentação de webhooks.
Depois, use POST /webhooks/{id}/test e consulte as entregas em GET /deliveries. Para callback, informe a URL no corpo de POST /operations e use o callback_secret fornecido ao criar a chave.
Valide a assinatura e processe cada evento uma vez
A assinatura chega em X-CriptoCore-Signature. Ela usa HMAC-SHA256 sobre o timestamp, um ponto e o corpo JSON original, sem reserializar. Verifique o timestamp e compare a assinatura em tempo constante, conforme os exemplos em verificação de assinaturas.
Após validar, persista event.id com unicidade, enfileire o processamento e responda 2xx. Entregas podem se repetir ou chegar fora de ordem. O identificador de entrega não substitui o identificador do evento para deduplicação.
Retentativas e recuperação por polling
Falhas de conexão ou respostas fora de 2xx geram novas tentativas conforme o contrato. Após esgotar o ciclo, consulte as entregas e reenvie as elegíveis com POST /deliveries/{id}/retry. Não há garantia de entrega única.
Use GET /events para consumir eventos por sequência e salve o cursor somente após processá-los. Para o estado financeiro atual de uma operação, consulte GET /operations/{id}. Respeite Retry-After e os limites de requisição.
Dúvidas frequentes
Preciso de um servidor público para usar a API?
Você precisa de um destino HTTPS público para receber webhooks ou callbacks. Se usar somente polling, seu backend pode consultar a API sem expor um endpoint de recebimento.
O evento de teste cobra ou transfere dinheiro?
Não. webhook.test testa a entrega ao endpoint sem movimentar saldo. Ele não simula uma liquidação financeira.
Como recuperar atualizações que meu sistema perdeu?
Consulte o histórico de entregas e os eventos por polling. Reenvie entregas elegíveis ou reconcilie o estado atual usando os IDs de operações e depósitos.