O mesmo evento pode chegar duas vezes?

Pode, e é de propósito: preferimos entregar duas vezes a perder um evento. Guarde o identificador do evento e ignore os repetidos. O número de sequência ajuda a descartar o que é mais antigo do que o estado que você já tem.

Posso testar sem gerar uma cobrança?

Pode. O evento de teste é real e assinado como qualquer outro, e a resposta mostra o que o seu servidor devolveu. Ele vai só para o endpoint testado, nunca para os demais inscritos.

Dá para apontar para o meu computador?

Em sandbox, numa instalação local, sim. Em servidor de produção o endereço interno é recusado mesmo no sandbox: para testar na sua máquina, use um túnel.

Integração

Seu sistema sabe na hora, e nada se perde

Cada mudança vira um evento com identificador e número de sequência. Se o seu endpoint cair, tentamos de novo por 24 horas e você ainda pode reenviar depois.

Assinatura HMAC verificável
Sete tentativas com jitter
Histórico e reenvio

Testar no sandbox Documentação de webhooks

Como funciona

1
Cadastre o endpoint
Uma URL https por ambiente, com os tipos de evento que interessam. Curinga vale para o recurso inteiro.
2
Valide a assinatura
Sobre o corpo bruto, antes de qualquer parse. Reserializar o JSON muda bytes e invalida a assinatura.
3
Ordene pelo número de sequência
Com retentativa, entregas chegam fora de ordem. O número cresce por organização e diz o que é mais recente.
4
Reconcilie quando precisar
A lista de eventos e o histórico de entregas mostram exatamente o que saiu, com o corpo que foi assinado.

No painel

As entregas

Cada entrega com o evento, o código devolvido pelo seu servidor, o tempo de resposta e a tentativa. A que falhou mostra quando será a próxima.

Entregas de um endpoint: uma falha de servidor recuperada na segunda tentativa.

No painel

O detalhe da entrega

A requisição como ela saiu, com os cabeçalhos e o corpo exato que foi assinado, e a resposta do seu servidor. O reenvio zera as tentativas.

Detalhe de uma entrega, com o corpo assinado e a resposta do servidor.

O que está incluído

Inscrição por tipo ou por curinga
Um tipo exato, todos de um recurso (inclusive os que forem criados depois) ou todos. Tipo que não existe é recusado no cadastro: um erro de digitação criaria um endpoint que nunca recebe nada.
payment.captured · payment.* · *
Assinatura com tempo, contra repetição
O cabeçalho leva o instante e o HMAC do instante com o corpo bruto. Calcule com o segredo inteiro e compare em tempo constante.
Minstrel-Signature: t=1736899200,v1=5257a869…
Rotação de segredo sem perder evento
Durante a janela de carência, o cabeçalho leva duas assinaturas e você aceita se qualquer uma casar. Em caso de vazamento, dá para invalidar na hora.
Sete tentativas, espaçadas
Imediata, 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas e 24 horas, com variação aleatória para não bater todas juntas no seu servidor. Confirmação é qualquer 2xx em até 10 segundos.
Desligar exige duas condições
Vinte falhas seguidas e três dias sem nenhuma entrega bem-sucedida. Uma queda de minutos, mesmo com muito volume, não desliga o seu endpoint.
Endereço interno é barrado duas vezes
No cadastro e de novo na hora da entrega, pelo IP resolvido. Assim um nome que aponta para a rede interna depois de cadastrado também não passa.

Envelope do evento

{  "id": "evt_01HQ8M5X7P2K3N4R5T6V7W8X9Y",  "type": "payment.captured",  "apiVersion": "2026-01-01",  "createdAt": "2026-01-15T14:32:10.123Z",  "environment": "live",  "sequence": 48213,  "data": {    "object": { "object": "payment", "id": "pay_...", "status": "captured" },    "previousAttributes": { "status": "authorized" }  }}

Documentação de webhooks

Dúvidas frequentes

O detalhe técnico de cada resposta está na documentação de webhooks.

O mesmo evento pode chegar duas vezes?
Pode, e é de propósito: preferimos entregar duas vezes a perder um evento. Guarde o identificador do evento e ignore os repetidos. O número de sequência ajuda a descartar o que é mais antigo do que o estado que você já tem.
Posso testar sem gerar uma cobrança?
Pode. O evento de teste é real e assinado como qualquer outro, e a resposta mostra o que o seu servidor devolveu. Ele vai só para o endpoint testado, nunca para os demais inscritos.
Dá para apontar para o meu computador?
Em sandbox, numa instalação local, sim. Em servidor de produção o endereço interno é recusado mesmo no sandbox: para testar na sua máquina, use um túnel.

Continua em

Veja funcionando no sandbox

Gratuito, ilimitado e sem prazo. Dá para simular aprovação, cada recusa da ABECS e falha de rede antes de credenciar a primeira adquirente.

Primeiros passos Ver preços