Skip to main content
Webhooks permitem que a AbacatePay envie notificações automáticas para o seu sistema sempre que um evento relevante ocorrer, como um pagamento aprovado ou uma assinatura renovada. Para entender como funcionam os webhooks, os eventos disponíveis e como validar as assinaturas HMAC, consulte a página de webhooks.

​
Criar webhook

Use POST /webhooks/create.

Campos obrigatórios

Obrigatórios: name, endpoint (URL HTTPS), secret, events.
Exemplo: 
POST /webhooks/create
{
  "name": "Meu Webhook de Pagamentos",                    // obrigatório - nome identificador do webhook
  "endpoint": "https://meusite.com/webhooks/abacatepay", // obrigatório - URL HTTPS que receberá os eventos
  "secret": "meu-secret-seguro",                         // obrigatório - chave usada para assinar os payloads
  "events": ["checkout.completed", "subscription.renewed"] // obrigatório - lista de eventos
}
Resposta: 
{
  "data": {
    "id": "webh_abc123xyz",
    "name": "Meu Webhook de Pagamentos",
    "endpoint": "https://meusite.com/webhooks/abacatepay",
    "events": ["checkout.completed", "subscription.renewed"],
    "devMode": false,
    "v2": true,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  },
  "success": true,
  "error": null
}

​
Eventos suportados

EventoQuando é disparado
checkout.completedPagamento de um checkout foi confirmado
checkout.refundedReembolso de um checkout foi concluído
checkout.disputedDisputa/chargeback aberta em um checkout
checkout.lostDisputa de checkout perdida
transparent.completedPagamento transparente confirmado
transparent.refundedReembolso de pagamento transparente concluído
transparent.disputedDisputa em pagamento transparente
transparent.lostDisputa de pagamento transparente perdida
subscription.completedAssinatura criada e ativada
subscription.cancelledAssinatura cancelada
subscription.renewedCobrança recorrente da assinatura paga
subscription.trial_startedPeríodo de trial iniciado
payout.completedSaque concluído com sucesso
payout.failedSaque falhou
transfer.completedTransferência concluída com sucesso
transfer.failedTransferência falhou

​
Modelo do webhook

O objeto retornado nas operações de criar, buscar e listar segue este formato:
CampoTipoDescrição
idstringIdentificador único do webhook
namestringNome do webhook
endpointstringURL HTTPS que recebe os eventos
eventsstring[]Lista de eventos subscritos
devModebooleanSe o webhook é de ambiente de testes
v2booleanSe o webhook usa o formato de payload v2
createdAtstringData de criação (ISO 8601)
updatedAtstringData da última atualização (ISO 8601)

​
Segurança

  • Requisições autenticadas via Bearer Token
  • O endpoint deve usar HTTPS e não pode apontar para endereços locais ou IPs privados
  • Abusos podem levar à suspensão da conta conforme os termos de uso