O que é webhook de pagamento

Webhook de pagamento é uma notificação HTTP que o gateway envia ao seu servidor quando um evento acontece — por exemplo, cobrança paga, reembolso ou assinatura renovada. Em vez de perguntar a API o tempo todo (polling), você cadastra uma URL HTTPS e recebe um POST com o evento. Na AbacatePay os webhooks são assinados e têm retentativa automática se o seu endpoint falhar.

Documentação: webhooks AbacatePay. Este post explica o conceito; a doc detalha payloads e segurança.

Webhook × polling

Polling é o seu sistema perguntando à API a cada poucos segundos: “esse pagamento já confirmou?”. Funciona, mas gasta request, atrasa a liberação e escala mal.

Webhook inverte o sentido: quando o evento acontece, a AbacatePay manda um POST para a URL que você cadastrou. É o aviso push — para servidores.

Use webhook para liberar pedido, ativar assinatura, registrar reembolso ou acompanhar saque. Use polling (ou consulta pontual na API) como rede de segurança se a URL cair — não como caminho principal.

Como funciona na prática

Em três passos:

1. Crie um endpoint HTTPS no seu backend (ex.: https://meusite.com/webhooks/abacatepay).
2. Cadastre a URL no dashboard da AbacatePay (nome, URL e secret).
3. Receba o POST quando o evento ocorrer — o corpo traz o campo event (ex.: checkout.completed, transparent.completed) e o objeto data.

Fluxo completo e telas do dashboard: docs de webhooks.

O que chega no payload

Os webhooks v2 compartilham o mesmo formato:

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

Campos que importam no dia a dia:

• id — identificador do evento; igual em todas as retentativas (use para idempotência)
• event — o tipo do aviso
• data — os dados da cobrança, assinatura, saque etc.
• devMode — se o evento veio do ambiente de teste

Dados sensíveis vêm mascarados: taxId parcialmente oculto; no cartão, só os últimos 4 dígitos e a bandeira. Os detalhes da validação HMAC estão na página de segurança dos webhooks.

Eventos que mais importam

Eventos da tabela oficial:

Assinaturas: /assinaturas. Saques e repasses: payouts.

Quer receber confirmação de pagamento no seu sistema? Fale com a gente.

Webhook no boleto e no Pix

No boleto emitido pelo painel, link, checkout ou API transparente, o pagamento confirmado chega por webhook. No fluxo transparente o evento documentado é transparent.completed — use esse nome no seu código.

Passo a passo de emissão: como emitir boleto online. Produto: boleto.

No Pix, o mesmo desenho vale: cobrança dinâmica + webhook + idempotência. Guia de conciliação: confirmar pagamento Pix automaticamente. Geração de QR: como gerar QR Code Pix via API. Produtos: /pix e /api-pix.

Segurança e boas práticas

Duas camadas recomendadas pela doc:

1. Secret na URL (webhookSecret na query) — seu endpoint confere o secret antes de processar.
2. Assinatura HMAC no header X-Webhook-Signature (HMAC-SHA256) — confere que o corpo não foi alterado. Implementação: segurança dos webhooks.

Outras regras da doc:

• Use HTTPS
• Responda 2xx em até 30 segundos — a AbacatePay considera entregue; o corpo da resposta é ignorado
• Responda 2xx depois de aceitar o evento de forma durável (a doc pede responder após concluir o processamento)
• Use o campo id para não processar o mesmo evento duas vezes
• 410 Gone desativa o webhook; redirecionamentos 3xx não são seguidos — cadastre a URL final; vários 4xx não geram retentativa

Retentativas (resumo)

Até 7 tentativas em cerca de 18 horas. Ao receber 2xx, as próximas param. Detalhes: entrega e retentativas.

Dev mode e produção

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

Teste o endpoint, a validação do secret/HMAC e a idempotência sem dinheiro real. Roteiro: como testar o gateway no sandbox. Hub de integração: /desenvolvedores.

Perguntas frequentes

O que é webhook de pagamento?

É o POST que o gateway envia à sua URL HTTPS quando um evento acontece (pagamento confirmado, reembolso, renovação de assinatura, saque etc.). Alternativa ao polling.

Qual a diferença entre webhook e consultar a API?

No polling, você pergunta. No webhook, o gateway avisa. Webhook reduz latência e carga; a consulta à API continua útil como fallback.

Quais eventos a AbacatePay envia?

Checkout, transparente, assinatura, transferência, saque e Pix por chave — ver a tabela completa na doc.

O que acontece se meu servidor estiver fora?

A AbacatePay retenta até 7 vezes (~18 h). Se você responder 410 Gone, o webhook é desativado.

Como evitar processar o mesmo pagamento duas vezes?

Guarde o id do evento. Nas retentativas o id se repete — se já processou, responda 200 sem repetir a ação.

Webhook avisa boleto pago?

Sim. No transparente o evento é transparent.completed. Emissão: como emitir boleto online. Produto: boleto.

Preciso validar a assinatura?

Sim. Confira o secret na URL e a assinatura HMAC no header. Detalhes: segurança dos webhooks.

Dá pra testar em sandbox/Dev mode?

Sim. Webhooks de Dev mode recebem eventos simulados. Guia: sandbox AbacatePay.

Quer receber confirmação de pagamento no seu sistema? Fale com a gente.

Leia também: como emitir boleto online · confirmar pagamento Pix automaticamente · pagamento recorrente · payouts · API Pix · desenvolvedores