Webhooks: notificações de pagamento em tempo real

​

Quando usar

​

Como funciona

​

Formato do evento

{
  "id": "log_Qw8eR2tY4uI6oP1aS3dF5gH7",
  "event": "checkout.completed",
  "apiVersion": 2,
  "devMode": false,
  "data": { }
}

​

Cliente, CPF e cartão

• Os eventos de checkout, checkout transparente e assinatura sempre trazem data.customer. Quando a cobrança não tem cliente, ele chega assim: { "id": "", "name": null, "email": null, "taxId": null }.
• O CPF ou CNPJ (taxId) chega mascarado: 123.***.789-** no CPF e 12.***.678/0001-** no CNPJ. O documento completo depende de liberação para a sua conta; fale com o suporte.
• Do cartão, só chegam os 4 últimos dígitos e a bandeira.
• Não valide o payload inteiro com um schema rígido (como Zod): campos novos podem ser adicionados, e o seu endpoint não deve quebrar por isso.

​

Eventos de webhook

​

Como criar um webhook pelo dashboard

1. Vá em Integração → Webhooks e clique em Criar webhook.
2. Em Versão do Webhook, escolha Webhook v2. A v1 cobre só eventos de cobrança e saque, não recebe nenhum evento desta página e vai ficar indisponível em breve.
3. Preencha o Nome, a URL (HTTPS e pública) e o Secret, com 32 caracteres ou mais.
4. Em Eventos, marque os eventos que esse webhook deve receber. Os de Pix por chave só aparecem para contas com o recurso liberado.
5. Clique em Salvar.

​

O que é o secret

​

Como criar um webhook pela API

curl -X POST https://api.abacatepay.com/v2/webhooks/create \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pagamentos da loja",
    "endpoint": "https://meusite.com/webhooks/abacatepay",
    "secret": "f72179170ec5a0c845c0fcd18457e241006d09363b2d2a7d296d7bffbcd027c4",
    "events": ["checkout.completed", "subscription.renewed"]
  }'

​

Requisitos da URL

• HTTPS em qualquer ambiente, inclusive no Modo Teste. Uma URL http:// é recusada.
• Endereço público. localhost e IPs privados ou reservados são recusados na criação. Se o domínio passar a apontar para um IP privado depois, a entrega é bloqueada e não é tentada de novo.
• URL final. Redirecionamentos (3xx) não são seguidos.
• Resposta rápida. Grave o evento (numa fila ou no banco) e responda 2xx logo em seguida. Processar tudo antes de responder arrisca passar dos 30 segundos.

​

Modo Teste e produção

​

Entrega e retentativas

​

Como evitar processar o mesmo evento duas vezes

1. Guarde o id de cada evento processado. As retentativas automáticas repetem o mesmo id. Se ele já foi processado, responda 2xx sem processar de novo.
2. Deixe a ação idempotente também pela entidade. O reenvio manual pelo dashboard chega com um id novo. Antes de liberar um pedido, confira se ele já não foi liberado, pelo id da cobrança ou da assinatura.

const eventId = req.body.id; // o mesmo em todas as retentativas automáticas

if (await db.events.findOne({ id: eventId })) {
  return res.status(200).json({ ok: true }); // já processado
}

await processEvent(req.body); // confira também se o pedido já foi liberado
await db.events.insert({ id: eventId, processedAt: new Date() });

return res.status(200).json({ ok: true });

• O mesmo checkout.id pode ter mais de um checkout.completed legítimo: o do upsell (isUpSell: true) e o de cada venda de um link de pagamento. Não descarte esses eventos só porque o checkout.id se repete.
• Cada cobrança paga de assinatura dispara dois eventos: o de assinatura (subscription.completed ou subscription.renewed) e um checkout.completed com frequency: "SUBSCRIPTION". Libere o acesso por um deles só.

​

Ordem de chegada

​

Logs, reenvio e desativação

• Cada tentativa aparece com o status, o evento, o ID da mensagem e a hora de envio. Clique numa linha para ver o Payload enviado e a Resposta da API, com o status HTTP e o tempo de resposta.
• Numa entrega que falhou, clique em Reenviar. O reenvio faz uma tentativa só, sem retentativas automáticas, e chega com um id novo.
• Para parar de receber, abra o menu do webhook e clique em Excluir. Não há opção para pausar.
• Um webhook é desativado automaticamente quando o seu endpoint responde 410 Gone. Para voltar a receber, crie um webhook novo.

​

Perguntas frequentes