POST assinado para a URL que você registrar, com os detalhes do pagamento.
Estes webhooks são de saída (1to1 → seu servidor). Você não os chama: você os
recebe. Cada entrega é assinada (padrão Standard Webhooks)
para que você verifique que veio de nós e não foi alterada.
Configurar um endpoint
No dashboard, em Configurações → API e Conexões, adicione a URL do seu sistema e escolha os eventos que quer receber. Ao criar, você recebe um signing secret (whsec_…) mostrado uma única vez — guarde-o como um segredo: é a chave com
que você verifica cada webhook. Você pode registrar até 10 endpoints por negócio.
Catálogo de eventos
payment.failed cobre apenas os pagamentos manuais marcados como falhos pela
sua equipe. As falhas de pagamentos online (cartão recusado, sessão expirada)
não emitem webhook.O payload
CadaPOST leva um corpo JSON com esta forma. O exemplo é um pagamento manual
creditado:
event_at é o momento em que o evento do pagamento ocorreu (para
payment.failed, a hora da falha). É diferente do header webhook-timestamp,
que é o instante de envio usado para a assinatura anti-replay.provider: "manual"):
bank_account (a etiqueta da conta em que o dinheiro entrou, ex.
"BANORTE 0876"), bank_datetime (data/hora no banco, opcional) e files
(comprovantes enviados). Em pagamentos online ficam null / []. Para cartão e
SPEI online use transaction_id e receipt_url.
Headers de cada entrega
string
Id único da entrega. Estável entre reenvios de um mesmo evento — use-o para
deduplicar (ver Entrega).
integer
Instante de envio (segundos Unix). Recomputado a cada reenvio e faz parte da
assinatura. Rejeite os que estiverem fora de uma janela razoável (±5 min) para
se proteger de replays.
string
Uma ou mais assinaturas
v1,<base64> separadas por espaço (haverá duas
durante uma rotação de secret). A entrega é válida se alguma coincidir.string
O tipo de evento (
payment.credited, payment.failed, …). Coincide com type
do corpo.string
Sempre
1to1-Webhooks/1.0.Verificar a assinatura
A assinatura é um HMAC-SHA256 do conteúdo{webhook-id}.{webhook-timestamp}.{body},
onde body é o corpo cru exato que você recebeu (não o re-serialize). A chave
é seu whsec_… com o prefixo removido e o resto decodificado de base64.
A forma mais simples é a biblioteca oficial do Standard Webhooks, que cuida da
rotação e da comparação em tempo constante por você:
Entrega e reenvios
1
Responda 2xx rápido
Responda com qualquer
2xx assim que receber o webhook. Se demorar mais de
10 segundos ou responder outro código, tratamos como falha e reenviamos.2
Deduplique por webhook-id
A entrega é at-least-once: um mesmo evento pode chegar mais de uma vez (um
reenvio após um timeout, por exemplo). O
webhook-id é estável entre
reenvios — guarde-o e descarte os repetidos.3
Não assuma ordem
Os eventos não chegam garantidamente em ordem. Use
data.payment.uuid +
status como a verdade, não a ordem de chegada: um payment.registered que
chegue atrasado não deve sobrescrever um payment.credited que você já
processou.4
Reenvios ~3 dias
Um endpoint fora do ar recebe reenvios com espaçamento crescente por ~3 dias.
Se continuar falhando, a assinatura é desabilitada automaticamente (após 5
falhas consecutivas esgotadas) — você a reativa pelo dashboard.
Rotacionar o secret
Pelo dashboard você pode rotacionar o signing secret quando quiser. Durante um período de graça de 24 horas, cada webhook é assinado com o secret novo e o anterior ao mesmo tempo (duas assinaturas no header). Assim você atualiza seu sistema sem perder nem rejeitar eventos: valide contra qualquer uma das duas; quando termina o período de graça de 24 h, o secret anterior deixa de assinar automaticamente.Comprovantes
Em um pagamento manual,files[] lista os comprovantes enviados com referências
estáveis — uuid, name e mime_type — mas sem URL de download: o payload é
um snapshot reenviado por dias, e uma URL assinada expiraria no caminho. O
download do arquivo é feito com sua API key por um endpoint autenticado
(documentado aqui quando disponível); enquanto isso, o uuid serve para
correlacionar o comprovante no dashboard.
Próximos passos
Autenticação
Como sua integração se autentica com a API key.
Erros
O contrato de erros da API pública.