Buscar...

Webhooks — Visão geral

Webhooks permitem que o OnnixPay notifique sua aplicação quando ocorrem eventos como conclusão de transação, recebimento PIX ou atualização de saldo. Sua aplicação deve expor uma URL pública que receberá requisições POST com o payload do evento.

Formato dos webhooks

O OnnixPay envia notificações com POST para a URL configurada, usando Content-Type: application/json. O corpo da requisição é um JSON com a estrutura abaixo.

Headers da requisição

  • Content-Type: application/json — payload em JSON
  • X-Webhook-Id — identificador único do evento (idempotência)
  • X-Webhook-Timestamp — timestamp Unix do envio
  • X-Webhook-Signature — assinatura HMAC (quando configurada)

Estrutura do payload (JSON)

Todo evento contém os campos de nível raiz e um objeto data com os dados do evento.

JSON
{
  "id": "evt_abc123xyz",
  "type": "transaction.completed",
  "created_at": "2025-02-09T14:30:00.000Z",
  "data": {
    "transaction_id": "txn_abc123",
    "status": "completed",
    "amount": 15000,
    "currency": "BRL",
    "metadata": {}
  }
}

Exemplo de requisição HTTP

HTTP
POST /sua-url-de-webhook HTTP/1.1
Host: seu-servidor.com
Content-Type: application/json
X-Webhook-Id: evt_abc123xyz
X-Webhook-Timestamp: 1707486600

{
  "id": "evt_abc123xyz",
  "type": "transaction.completed",
  "created_at": "2025-02-09T14:30:00.000Z",
  "data": { ... }
}

Assinatura e retentativas

(Definir: se há assinatura HMAC para validar a origem; política de retentativas e tempo de expiração.)

Recursos