Desenvolvedores · Webhooks
Eventos confiáveis para manter seu sistema atualizado.
Webhooks notificam mudanças sem depender de consulta contínua. O endpoint deve validar autenticidade, responder rápido, deduplicar eventos e processar tarefas demoradas fora da requisição.

Visão executiva
O essencial antes de operar
Intenção atendida: Implementar webhooks com autenticidade, resposta rápida, deduplicação, retentativas e observabilidade.
- Webhooks podem chegar repetidos e fora de ordem.
- Assinatura é validada sobre os bytes corretos.
- O endpoint responde rápido antes do processamento pesado.
- O estado é consultado quando houver dúvida.
- Reprocessamento preserva idempotência e auditoria.
01
O que esta solução organiza
Webhooks notificam mudanças sem depender de consulta contínua. O endpoint deve validar autenticidade, responder rápido, deduplicar eventos e processar tarefas demoradas fora da requisição. O desenho da jornada separa claramente solicitação, validação, confirmação e conciliação. Assim, cada participante sabe o que precisa ocorrer antes de avançar.
Atualização de status orientada a eventos
Validação da origem de cada provedor
Reprocessamento seguro e observável
02
Como funciona, etapa por etapa
- 01
Exponha um endpoint HTTPS dedicado
- 02
Valide assinatura ou segredo antes de processar
- 03
Registre e deduplique o identificador do evento
- 04
Responda rápido e processe com retentativas
03
Qualidade operacional por padrão
Antes de confirmar qualquer operação, revise titularidade, valores, moeda ou ativo, rede quando aplicável, prazos, tarifas e destinatários. Dados enviados por canais não verificados não devem ser usados para transferências.
A Digittro apresenta estas informações para explicar o produto, e não como promessa de aprovação, rentabilidade, disponibilidade contínua ou aconselhamento financeiro, jurídico ou tributário.
03
Receber não significa confiar
O endpoint HTTPS recebe eventos, mas só processa depois de validar o mecanismo de autenticidade documentado, timestamp e tolerância de replay. Quando a assinatura depende do corpo bruto, o framework não pode reserializar o JSON antes da verificação. Segredos diferentes são usados por ambiente e destino.
Firewall por IP pode complementar controles, mas não substitui assinatura quando o provedor oferece mecanismo criptográfico. A aplicação também limita tamanho, método e tipo de conteúdo antes de colocar o evento na fila.
04
Responder rápido e processar com segurança
Após validar e persistir o evento, o endpoint responde no prazo esperado. Consultas lentas, envio de e-mail e atualizações complexas seguem em processamento assíncrono. Uma falha interna não deve manter a conexão aberta até expirar nem perder o payload recebido.
O identificador do evento é único para deduplicação. Se a mesma entrega chegar novamente, o consumidor retorna sucesso quando o resultado já foi aplicado. Eventos de objetos diferentes podem ser paralelos; eventos do mesmo agregado precisam respeitar versão ou estado atual.
05
Ordem, retentativa e reconciliação
A rede não garante que eventos cheguem na ordem do negócio. O consumidor verifica timestamp, versão ou consulta a API quando uma transição não fizer sentido. Ele não regride um pagamento liquidado para pendente apenas porque recebeu uma entrega atrasada.
Retentativas usam backoff e entram em dead-letter ou fila de exceção após o limite. O painel permite reprocessar com permissão e registra resultado anterior. Métricas mostram entregas, falhas de assinatura, tempo de processamento, retries e backlog sem expor dados sensíveis.
Reconciliação periódica compara objetos da API com estados locais, cobrindo eventos definitivamente perdidos. Webhook reduz polling, mas não é a única fonte de recuperação operacional.
Mudanças de endpoint seguem rotação controlada: o novo destino é validado, recebe teste identificado e só então substitui o anterior. O painel mostra última entrega, código HTTP e próxima tentativa sem exibir o segredo. Desativar um endpoint interrompe novas entregas, mas preserva histórico e permite exportar eventos para investigação.
Consumidores registram o schema ou versão do evento e ignoram campos adicionais desconhecidos. Campos obrigatórios não são removidos sem migração e aviso. Essa tolerância controlada permite evolução sem transformar qualquer acréscimo compatível em incidente.
Comparativo
Webhooks: entrega, verificação e recuperação
| Dimensão | Contrato necessário | Evidência |
|---|---|---|
| Requisição | Método, rota, campos e autenticação | Exemplo e schema |
| Resposta | Status, corpo e identificador | Contrato versionado |
| Falha | Código, detalhe e possibilidade de retry | Erro estruturado |
| Repetição | Idempotência e deduplicação | Chave e resultado original |
| Operação | Logs, métricas e correlação | Request ID e auditoria |
A documentação pública deve descrever somente recursos realmente implementados e disponíveis no ambiente correspondente.
Checklist
Antes de solicitar uma cotação
- 01
Definir caso de uso e ambiente.
- 02
Criar credencial com privilégio mínimo.
- 03
Validar contrato e exemplos oficiais.
- 04
Implementar timeout, retry e idempotência.
- 05
Tratar erros por código e estado.
- 06
Validar eventos e assinaturas no servidor.
- 07
Monitorar request IDs, latência e falhas.
Vocabulário
Termos usados nesta página
- API
- Interface programática com contrato documentado.
- Endpoint
- Combinação de método e rota para um recurso.
- Request ID
- Identificador usado para correlacionar uma requisição.
- Idempotência
- Repetição segura que preserva o efeito esperado.
- Webhook
- Evento enviado para um endpoint do integrador.
- Escopo
- Conjunto de permissões associado à credencial.
Fontes
Referências institucionais
Links externos usados para contextualização normativa e educação financeira. Nenhum direciona a concorrentes.
04
Perguntas frequentes
Posso confiar em qualquer POST recebido?+
Não. Valide o mecanismo de autenticidade específico do provedor.
Por que recebo o mesmo evento mais de uma vez?+
Retentativas são normais; o consumidor precisa ser idempotente.
Devo executar tarefas lentas no endpoint?+
Evite. Registre o evento, responda e processe de forma assíncrona quando possível.