Pular para o conteúdo principal

​
Visão Geral

Webhooks permitem que você receba notificações HTTP automáticas quando eventos importantes acontecem na sua conta, como pagamentos confirmados ou reembolsos processados.

​
Eventos Disponíveis

EventoDescrição
payment_completedPagamento foi confirmado com sucesso
payment_failedPagamento falhou ou expirou
refund_completedReembolso foi processado

​
Estrutura do Payload

Todos os webhooks seguem a mesma estrutura base: 
{
  "event": "payment_completed",
  "eventId": "txn_abc123def456",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    // Dados específicos do evento
  }
}
CampoTipoDescrição
eventstringTipo do evento
eventIdstringID único do evento (geralmente o ID da transação)
timestampstringData/hora do evento em formato ISO 8601
dataobjectDados específicos do evento

​
Headers Enviados

Cada requisição de webhook inclui os seguintes headers:
HeaderDescrição
Content-Typeapplication/json
X-Webhook-SignatureAssinatura HMAC-SHA256 do payload
X-Webhook-TimestampTimestamp em milliseconds

​
Exemplos de Payload

​
payment_completed

Enviado quando um pagamento PIX é confirmado. 
{
  "event": "payment_completed",
  "eventId": "txn_abc123def456",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "transactionId": "txn_abc123def456",
    "amount": 100.50,
    "feeAmount": 0.99,
    "netAmount": 99.51,
    "currency": "BRL",
    "paymentMethod": "pix",
    "status": "completed",
    "completedAt": "2024-01-15T10:30:00.000Z"
  }
}

​
payment_failed

Enviado quando um pagamento falha ou expira. 
{
  "event": "payment_failed",
  "eventId": "txn_xyz789ghi012",
  "timestamp": "2024-01-15T10:35:00.000Z",
  "data": {
    "transactionId": "txn_xyz789ghi012",
    "amount": 50.00,
    "currency": "BRL",
    "paymentMethod": "pix",
    "status": "failed",
    "failedAt": "2024-01-15T10:35:00.000Z",
    "failureReason": "expired"
  }
}

​
refund_completed

Enviado quando um reembolso é processado. 
{
  "event": "refund_completed",
  "eventId": "txn_ref456jkl789",
  "timestamp": "2024-01-15T11:00:00.000Z",
  "data": {
    "refundTransactionId": "txn_ref456jkl789",
    "originalTransactionId": "txn_abc123def456",
    "amount": 100.50,
    "feeAmount": 0,
    "currency": "BRL",
    "status": "completed",
    "refundedAt": "2024-01-15T11:00:00.000Z"
  }
}

​
Boas Práticas

Retorne um status 200 OK o mais rápido possível. Processe o webhook de forma assíncrona se necessário.
Use o eventId para evitar processar o mesmo evento duas vezes. Webhooks podem ser reenviados em caso de falha.
Configure seu endpoint apenas com HTTPS para garantir a segurança dos dados.

​
Retentativas

Se o seu endpoint não responder com status 2xx, tentaremos reenviar o webhook:
  • 5 tentativas com backoff exponencial
  • Intervalo inicial: 2 segundos
  • Intervalo máximo: ~30 segundos entre tentativas
Após 5 tentativas sem sucesso, o webhook é marcado como falho.