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:

{
  "amount": 2750,
  "id": "3f0b3b28-2a4a-4a9f-9f6b-1e3d2c6a7b91",
  "method": "pix",
  "external_id": "external_id",
  "payee": {
    "bank": {
      "account": "98765432",
      "agency": "4321",
      "digit": "0",
      "name": "Itaú Unibanco",
      "type": "Conta Corrente"
    },
    "document": "45.987.321/0001-10",
    "name": "Empresa Exemplo LTDA",
    "pix_key": "financeiro@exemplo.com.br"
  },
  "payer": {
    "address": {
      "address": "Av. das Acácias",
      "address_number": "1200",
      "city": "Salvador",
      "complement": "Sala 504",
      "country": "BR",
      "neighborhood": "Pituba",
      "postal_code": "41830478",
      "state": "BA"
    },
    "document": "12345678909",
    "email": "joao.silva@example.com",
    "name": "João da Silva",
    "phone": "11987654321"
  },
  "status": "paid",
  "total": 2750
}

Exemplo de payload Cartão:

{
  "amount": 2750,
  "id": "3f0b3b28-2a4a-4a9f-9f6b-1e3d2c6a7b91",
  "method": "credit_card",
  "external_id": "external_id",
  "payee": {
    "bank": {
      "account": "98765432",
      "agency": "4321",
      "digit": "0",
      "name": "Itaú Unibanco",
      "type": "Conta Corrente"
    },
    "document": "45.987.321/0001-10",
    "name": "Empresa Exemplo LTDA",
    "pix_key": "financeiro@exemplo.com.br"
  },
  "payer": {
    "address": {
      "address": "Av. das Acácias",
      "address_number": "1200",
      "city": "Salvador",
      "complement": "Sala 504",
      "country": "BR",
      "neighborhood": "Pituba",
      "postal_code": "41830478",
      "state": "BA"
    },
    "document": "12345678909",
    "email": "joao.silva@example.com",
    "name": "João da Silva",
    "phone": "11987654321"
  },
  "status": "paid",
  "total": 2750
}

🧾 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#