Webhooks

🔄 Webhooks

Receba atualizações em tempo real sobre eventos da sua integração por meio de notificações de webhook.

🧭 Visão Geral

Os webhooks permitem que sua aplicação receba notificações automáticas sempre que eventos específicos ocorrerem em nosso sistema. Em vez de consultar constantemente a API em busca de atualizações, os webhooks enviam os dados diretamente para sua aplicação assim que o evento acontece.

🚀 Configurando Webhooks

O webhook é enviado através do campo "postback_url" na rota Criação de Invoices

📬 Estrutura do Payload

Quando um evento ocorre, nosso sistema envia uma requisição POST para a URL configurada, contendo um payload em formato JSON.

Exemplo de payload PIX:

{
    "id": "id",
    "status": "paid",
    "total": 1990,
    "method": "pix"
}

Exemplo de payload Cartão:

{
    "id": "id",
    "status": "paid",
    "total": 1990,
    "method": "credit_card"
}

🧾 Campos do Payload

Campo	Tipo	Descrição
id	string	Identificador único da fatura
status	string	Status atual da fatura (ex.: "paid", "pending", "failed", "chargeback", "refused", "refunded", "error", "pending")
total	integer	Valor total em centavos
method	string	Método de pagamento utilizado (ex.: "pix", "credit_card", "bank_transfer")

🔁 Respondendo a Webhooks

Seu endpoint de webhook deve retornar um código HTTP 2xx para confirmar o recebimento da notificação.
Se nosso sistema não receber uma resposta 2xx, ele tentará reenviar o webhook até 10 vezes, com intervalos crescentes entre as tentativas (exponential backoff).

🧪 Testando Webhooks (Em Desenvolvimento)

Você pode testar sua implementação de webhooks usando o simulador de webhooks disponível no painel do desenvolvedor. Ele permite enviar payloads de teste para o seu endpoint sem precisar acionar eventos reais.

⚠️ Recomendações de Segurança

Verifique a autenticidade do webhook utilizando a assinatura enviada nos cabeçalhos da requisição

Implemente tratamento de erros adequado para as requisições recebidas

Use sempre HTTPS no endpoint do webhook

Configure monitoramento para acompanhar as entregas e falhas dos webhooks

📅 Eventos Comuns de Webhook

Evento	Descrição
invoice.created	Disparado quando uma nova fatura é criada
invoice.paid	Disparado quando uma fatura é paga com sucesso
invoice.failed	Disparado quando uma tentativa de pagamento falha
invoice.canceled	Disparado quando uma fatura é cancelada

Precisa de ajuda? Entre em contato com nossa equipe de suporte para desenvolvedores para obter assistência.

🔄 Webhooks#

🧭 Visão Geral#

🚀 Configurando Webhooks#

#

📬 Estrutura do Payload#

🧾 Campos do Payload#

🔁 Respondendo a Webhooks#

🧪 Testando Webhooks (Em Desenvolvimento)#

⚠️ Recomendações de Segurança#

📅 Eventos Comuns de Webhook#