Skip to main content
Os webhooks avisam você em tempo real, no seu próprio servidor, sempre que um pagamento muda de estado — sem precisar consultar a API em loop. A 1to1 envia um 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.
A URL deve ser https:// e pública. Guarde o whsec_… em um lugar seguro do servidor (variável de ambiente, secret manager) — nunca em código cliente nem no repositório. Se perdê-lo, rotacione o secret pelo dashboard.

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

Cada POST 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.
Alguns campos são exclusivos de pagamentos manuais (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.
conversation_info.uuid pode ser null se a conversa associada foi excluída — o pagamento notifica mesmo assim (o webhook é do ciclo de vida do pagamento, não da conversa). Sempre correlacione por data.payment.uuid.

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.
Verifique sobre o corpo cru (raw body), antes de parsear o JSON. Re-serializar o objeto muda bytes (espaços, ordem das chaves) e quebra a assinatura.
A forma mais simples é a biblioteca oficial do Standard Webhooks, que cuida da rotação e da comparação em tempo constante por você:
Se preferir verificar na mão (sem dependências), replique o HMAC e compare em tempo constante contra cada assinatura do header:

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.