Skip to main content

​
Visão Geral

A plataforma envia webhooks para URLs configuradas pelos clientes quando eventos importantes acontecem no sistema. Os webhooks permitem que você receba notificações em tempo real sobre mudanças de status em cobranças, transferências e estornos.

​
Características Principais

  • Autenticação Segura: Assinatura HMAC SHA-256 para validação
  • Múltiplos Webhooks: Suporte a múltiplos endpoints por conta
  • Eventos em Tempo Real: Notificações imediatas quando eventos ocorrem

​
Estrutura Geral

  • Método: POST
  • Content-Type: application/json
  • Autenticação: Assinatura HMAC SHA-256 no header X-Webhook-Signature
  • Timeout: 5 segundos por requisição

​
Estrutura do Payload

Todos os webhooks seguem a mesma estrutura base: 
{
  "event": "PAYMENT",
  "data": {
    // Dados específicos do evento
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Headers Enviados

Cada webhook inclui os seguintes headers:
  • Accept: application/json
  • Content-Type: application/json
  • User-Agent: {app_name}/1.0.0
  • X-Webhook-Event: Nome do evento (ex: “PAYMENT”, “TRANSFER”, “REFUND”)
  • X-Webhook-Timestamp: Timestamp ISO 8601 do envio
  • X-Webhook-Signature: Assinatura HMAC SHA-256 do payload completo

​
Tipos de Eventos

A plataforma envia três tipos principais de eventos:
  1. PAYMENT - Eventos relacionados a cobranças PIX In
  2. TRANSFER - Eventos relacionados a transferências PIX Out
  3. REFUND - Eventos relacionados a estornos

​
Resposta Esperada

O endpoint do cliente deve responder com:
  • Status HTTP 2xx (200-299): Considerado sucesso
  • Qualquer outro status: Considerado falha
A resposta não precisa ter um formato específico, apenas um status HTTP válido.
Sempre valide a assinatura HMAC antes de processar o webhook para garantir que a requisição é legítima.