Receba webhooks
Como a Accelerazione notifica o seu servidor sobre desfechos de cobranças e estornos, e o contrato que o seu endpoint precisa cumprir.
Quando uma cobrança ou um estorno chega a um desfecho, a Accelerazione envia um POST para a URL que você informou em postbackUrl na criação da cobrança. O webhook evita que você precise consultar a API em intervalos para descobrir se um Pix foi pago.
Configure a URL
A URL é definida por cobrança, no campo postbackUrl de POST /api/v1/paymentintents. Todos os eventos daquela cobrança e dos estornos dela vão para a mesma URL. Sem postbackUrl, nenhum webhook é enviado.
- Use uma URL HTTPS absoluta, acessível pela internet.
- Não use redirecionamento: em
301ou302, oPOSTviraGETe o corpo se perde. - A URL não é validada na criação da cobrança. Uma URL inválida não gera erro na API: os webhooks simplesmente não chegam. Teste a URL no sandbox.
O que chega
POST /webhooks/dm HTTP/1.1
Content-Type: application/json; charset=utf-8
X-DM-Signature: t=1788876000,v1=5f0c...e91a
X-DM-Webhook-Id: 3f1c2b9e-7a64-8d2f-b1e0-6c5a4d3e2f10
{"eventType":"payment_intent.succeeded","data":{"id":"8b727267-bf39-48a4-91ea-eb0780cb48a9","object":"payment_intent","amount":1990,"currency":"BRL","status":"Succeeded", ...}}O corpo tem sempre dois campos: eventType, que diz o que aconteceu, e data, com o retrato do recurso naquele momento. Os tipos de evento e o formato de data estão em Eventos.
Contrato do seu endpoint
Leia o corpo cru e confira a autenticidade
Guarde os bytes exatos recebidos antes de qualquer middleware converter o JSON. A verificação HMAC é calculada sobre esses bytes.
Grave o evento de forma durável
Persista o evento no banco ou numa fila antes de responder. Se o seu processo cair depois do 200, o evento não será reenviado.
Responda 200
Responda exatamente 200, em poucos segundos. 201, 202 e 204 contam como falha e geram reenvio. O tempo limite é de 30 segundos; mire em menos de 10.
Processe fora da requisição
Aplique a transição no pedido de forma assíncrona e idempotente. Tarefas demoradas, como emitir nota ou mandar e-mail, nunca rodam dentro da requisição do webhook.
Reenvios
Qualquer resposta diferente de 200, inclusive 4xx, e qualquer falha de rede ou tempo esgotado gera nova tentativa. São até três tentativas, com cerca de 60 segundos entre elas. O corpo e a assinatura são os mesmos em todas.
Depois da terceira falha, o evento não é mais enviado automaticamente. Por isso o webhook não pode ser a única fonte da verdade: mantenha uma rotina que consulte GET /api/v1/paymentintents/{id} para pedidos que ficaram tempo demais sem desfecho.
Não dependa de uma agenda fixa de reenvios na lógica do checkout. O número e o intervalo das tentativas podem mudar.
Duplicatas e ordem
A entrega é pelo menos uma vez, e sem garantia de ordem. Projete o processamento para estes casos:
| Situação | Como tratar |
|---|---|
| O mesmo evento chega duas vezes | Deduplique por X-DM-Webhook-Id. O valor é o mesmo em todos os reenvios do mesmo evento. |
| O evento chega antes da resposta do create | Guarde o evento autenticado mesmo sem vínculo local e processe quando o PaymentIntent estiver gravado, inclusive por uma repetição idempotente do create. Não descarte um evento só por ele ter chegado primeiro. |
| Eventos fora de ordem | Nunca regrida um pedido. Um succeeded atrasado não desfaz um estorno já confirmado. Em dúvida, consulte o PaymentIntent. |
| Mesmo pagamento, eventos diferentes | Deduplicar só por data.id não basta: o mesmo pagamento pode ter sucesso e depois estorno. Use o par eventType + data.id, e acrescente data.refundId nos eventos de estorno. |
| Pix pago depois de expirar | Um Pix confirmado depois do prazo gera payment_intent.succeeded para uma cobrança que estava Canceled. Aceite a confirmação tardia. |
Sem assinatura, sem identificador
X-DM-Webhook-Id acompanha a assinatura. Se a sua conta ainda não tem segredo de assinatura habilitado, o webhook chega sem esses cabeçalhos; nesse caso deduplique pelo par eventType + data.id (+ data.refundId) e confirme o estado pela API antes de alterar o pedido.
O que não tem webhook
Estes acontecimentos não geram webhook. Acompanhe-os pela resposta da API e pela consulta:
- criação da cobrança e estados intermediários (
Processing,RequiresAction); - desafio 3DS;
- expiração e cancelamento de Pix e de Pix parcelado (a cobrança passa a
Canceled); - saques.
Libere a origem no firewall
Todas as requisições trazem um cabeçalho fixo de origem, no formato X-DM-<uuid>: <uuid>, igual em todas as entregas. Ele serve para regras de firewall ou WAF que precisam identificar o tráfego da Accelerazione. Peça o valor à equipe de integração. Esse cabeçalho não autentica a mensagem: quem autentica é a assinatura HMAC.