Webhooks - AbacatePay

Pense nos webhooks como “mensagens enviadas pela AbacatePay para o seu sistema”, sem que você precise ficar consultando a API o tempo todo.

Por que usar webhooks?

Sem webhooks, sua aplicação teria que perguntar para a API a cada segundo:

“Esse pagamento já foi confirmado?”

Isso é lento e ineficiente. Com webhooks, a AbacatePay avisa você imediatamente:

“O pagamento foi confirmado. Aqui estão os dados.”

Assim você pode:

atualizar o status de um pedido
liberar acesso a um produto
enviar e-mails automáticos
registrar movimentações financeiras

Tudo isso sem precisar fazer nada manualmente, e sem fazer seu cliente esperar.

Como funciona na prática?

Você cria um endpoint no seu sistema
Ex.: https://meusite.com/webhooks/abacatepay
Você cadastra esse endpoint no dashboard da AbacatePay
Sempre que algo importante acontece, como um pagamento aprovado:
- A AbacatePay envia um POST para a sua URL
- O POST contém o evento (ex: checkout.completed, transparent.completed)
- Seu sistema processa esse evento

É como receber uma notificação push — só que para servidores.

Ambientes (Dev mode vs Produção)

Ambientes da AbacatePay

Webhooks criados em Dev mode recebem eventos simulados
Webhooks criados em Produção recebem eventos reais

Dessa forma, você pode testar tudo antes de ir para produção.

Segurança dos webhooks

Webhooks precisam ser seguros — afinal, qualquer pessoa poderia tentar enviar requisições falsas para sua aplicação. Por isso, recomendamos duas camadas de proteção: 1. Secret na URL — cada webhook tem uma chave secreta que vai junto com a URL. Seu sistema verifica se essa chave está correta antes de processar o evento. 2. Assinatura digital (HMAC) — a AbacatePay assina cada evento que envia. Seu sistema pode confirmar que o evento realmente veio da AbacatePay e que não foi alterado no caminho. É o mesmo método usado por Stripe, PayPal, Shopify e GitHub.

A configuração de segurança é feita pelo seu desenvolvedor. Veja a documentação técnica completa na página de segurança de webhooks.

Ver implementação — Secret na URL (Node.js)

Cada webhook tem um secret único, que vai na query string da URL:https://meusite.com/webhook/abacatepay?webhookSecret=SEU_SECRET

if (req.query.webhookSecret !== process.env.WEBHOOK_SECRET) {
  return res.status(401).json({ error: "Unauthorized" });
}

Ver implementação — Validação HMAC (Node.js)

Cada webhook enviado pela AbacatePay inclui uma assinatura no header X-Webhook-Signature gerada com HMAC-SHA256.

import crypto from "node:crypto";

const ABACATEPAY_PUBLIC_KEY =
  "t9dXRhHHo3yDEj5pVDYz0frf7q6bMKyMRmxxCPIPp3RCplBfXRxqlC6ZpiWmOqj4L63qEaeUOtrCI8P0VMUgo6iIga2ri9ogaHFs0WIIywSMg0q7RmBfybe1E5XJcfC4IW3alNqym0tXoAKkzvfEjZxV6bE0oG2zJrNNYmUCKZyV0KZ3JS8Votf9EAWWYdiDkMkpbMdPggfh1EqHlVkMiTady6jOR3hyzGEHrIz2Ret0xHKMbiqkr9HS1JhNHDX9";

export function verifyAbacateSignature(rawBody: string, signatureFromHeader: string) {
  const bodyBuffer = Buffer.from(rawBody, "utf8")

  const expectedSig = crypto
    .createHmac("sha256", ABACATEPAY_PUBLIC_KEY)
    .update(bodyBuffer)
    .digest("base64");

  const A = Buffer.from(expectedSig);
  const B = Buffer.from(signatureFromHeader);

  return A.length === B.length && crypto.timingSafeEqual(A, B);
}

Criando um webhook no dashboard

Acesse a seção de Webhooks

Abra a área de Webhooks

É aqui que você cria e gerencia seus endpoints de notificação.

Clique em Criar

Inicie a configuração

Informe o nome e a URL que receberá os eventos.

Configure os detalhes

O que você deve informar:

Nome: Ex.: “Pagamentos confirmados”
URL: Endpoint HTTPS que receberá os eventos
Secret: Chave usada para verificar a autenticidade

Eventos suportados

Evento	Quando é disparado
`checkout.completed`	Pagamento de um checkout foi confirmado
`checkout.refunded`	Reembolso de um checkout foi concluído
`checkout.disputed`	Disputa/chargeback aberta em um checkout
`transparent.completed`	Pagamento de um checkout transparente confirmado
`transparent.refunded`	Reembolso de um checkout transparente foi concluído
`transparent.disputed`	Disputa/chargeback aberta em um pagamento transparente
`subscription.completed`	Assinatura criada e ativada
`subscription.cancelled`	Assinatura cancelada
`subscription.renewed`	Cobrança recorrente da assinatura foi paga
`transfer.completed`	Transferência concluída com sucesso
`transfer.failed`	Transferência falhou
`payout.completed`	Saque concluído com sucesso
`payout.failed`	Saque falhou

Todos os webhooks v2 compartilham o mesmo formato de payload:

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

Dados sensíveis: O campo taxId (CPF/CNPJ) é mascarado nos payloads (ex: 123.***.***-**). Para pagamentos com cartão, apenas os últimos 4 dígitos e a bandeira são enviados.

Os payloads detalhados de cada evento estão documentados individualmente na seção Eventos na barra lateral.

Estrutura dos payloads

Quando `customer` está vazio

Se não houver cliente vinculado ao checkout, pagamento ou assinatura, o objeto customer será null.

Entrega e retentativas

A AbacatePay considera um webhook entregue quando seu endpoint responde com qualquer status 2xx em até 30 segundos. O corpo da resposta é ignorado. Se a entrega falhar por um motivo temporário, a AbacatePay tenta de novo automaticamente, com intervalos cada vez maiores:

Tentativa	Quando acontece
1ª (original)	Assim que o evento acontece
2ª	5 segundos após a falha anterior
3ª	5 minutos após a falha anterior
4ª	30 minutos após a falha anterior
5ª	2 horas após a falha anterior
6ª	5 horas após a falha anterior
7ª (última)	10 horas após a falha anterior

No total, são até 7 tentativas ao longo de cerca de 18 horas. Assim que uma delas recebe 2xx, as próximas são canceladas.

Quais respostas geram retentativa

Resposta do seu endpoint	O que a AbacatePay faz
`2xx`	Considera entregue
Sem resposta em 30s, erro de conexão, DNS ou TLS	Tenta de novo
`5xx`	Tenta de novo
`408 Request Timeout` ou `429 Too Many Requests`	Tenta de novo
`410 Gone`	Desativa o webhook e não tenta de novo
`3xx` ou outros `4xx` (ex.: `400`, `401`, `404`)	Não tenta de novo

Redirecionamentos (3xx) não são seguidos. Cadastre a URL final do seu endpoint. Respostas 4xx normalmente indicam URL errada ou falha na validação do secret/assinatura, então repetir o envio não resolveria.

O mesmo evento pode chegar mais de uma vez

Todas as tentativas de um mesmo evento chegam com o mesmo id no corpo. Use esse campo para ignorar duplicatas: se o id já foi processado, responda 200 OK sem processar de novo. Isso também protege seu sistema quando ele processa o evento mas a resposta não chega à AbacatePay (por exemplo, por timeout).

const eventId = req.body.id; // o mesmo em todas as tentativas

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

await processEvent(req.body);
await db.events.insert({ id: eventId, processedAt: new Date() });

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

Outros detalhes

Cada tentativa aparece nos logs do webhook no dashboard, com o status e o tempo de resposta.
Se você desativar ou excluir o webhook, as retentativas pendentes são descartadas.
O reenvio manual de um log pelo dashboard faz uma única tentativa, sem retentativas automáticas, e gera um novo id.
As retentativas funcionam igual em Dev mode e em Produção.

Boas práticas

Recomendações importantes

Use HTTPS em todos os webhooks
Valide o secret e a assinatura HMAC
Registre cada evento recebido — processe cada um uma única vez
Responda 200 OK somente após concluir o processamento
Use o campo id para ignorar eventos repetidos — retentativas reenviam o mesmo id
Responda rápido: acima de 30 segundos a entrega é considerada falha
Não realize validação do payload inteiro dos webhooks (como com Zod), evitando que mudanças futuras não quebrem seu endpoint

Precisa de ajuda?

Nossa equipe pode te ajudar. Contate-nos: ajuda@abacatepay.com

​Por que usar webhooks?

​Como funciona na prática?

​Ambientes (Dev mode vs Produção)

Ambientes da AbacatePay

​Segurança dos webhooks

​Criando um webhook no dashboard

Abra a área de Webhooks

Inicie a configuração

O que você deve informar:

​Eventos suportados

​Estrutura dos payloads

​Quando customer está vazio

​Entrega e retentativas

​Quais respostas geram retentativa

​O mesmo evento pode chegar mais de uma vez

​Outros detalhes

​Boas práticas

Recomendações importantes

Precisa de ajuda?

Por que usar webhooks?

Como funciona na prática?

Ambientes (Dev mode vs Produção)

Segurança dos webhooks

Criando um webhook no dashboard

Eventos suportados

Estrutura dos payloads

Quando `customer` está vazio

Entrega e retentativas

Quais respostas geram retentativa

O mesmo evento pode chegar mais de uma vez

Outros detalhes

Boas práticas