Webhooks · OnnixPay Docs

Webhooks

Webhooks notificam seu sistema quando algo acontece com uma cobrança ou um pagamento, sem polling. Cada evento é um POST assinado para a sua URL.

Dois caminhos de entrega

Você recebe eventos por dois meios, complementares:

O webhook_url informado na criação da cobrança ou do pagamento recebe os eventos daquele recurso.
Os webhooks configurados no dashboard recebem os eventos de todas as cobranças e pagamentos do Merchant.

Anatomia de um evento

Todo webhook tem o mesmo envelope, qualquer que seja o tipo:

id: identificador único do evento, use para dedup.
type: o tipo do evento, sempre no formato recurso.acao (ex.: charge.paid).
created_at: quando o evento ocorreu, em ISO 8601.
data: o objeto relacionado (a cobrança, o pagamento, a disputa).

Os mesmos dados vão nos headers x-onnix-event, x-onnix-event-id e x-onnix-signature, para você rotear e validar sem precisar desserializar o corpo.

Famílias de eventos

Os eventos são agrupados por recurso. O catálogo completo traz a descrição e o payload de cada um.

charge.*: criação, pagamento, expiração, cancelamento, disputa e estorno de cobranças.
pix.*: recebimentos, envios, falhas e devoluções.
pix.infraction.*: contestação (MED) aberta, confirmada ou negada.
ted.* e boleto.*: liquidação e falha por canal.
bill_payment.*: conta paga, falha e estorno.
transfer.*, balance.*, account.* e kyc.*: transferências internas, saldo e situação cadastral.

Confirmação e retentativas

Responda com 2xx rapidamente. Qualquer outro status ou timeout faz o evento ser reenviado com backoff exponencial por até 24 horas. Como pode haver reentrega, processe de forma idempotente usando o id do evento.

Um evento nunca é a única fonte de verdade: se você perdeu a entrega, consulte o recurso pela API antes de decidir. E não dependa da ordem de chegada: dois eventos do mesmo recurso podem chegar fora de sequência.

Sempre verifique a assinatura

Antes de confiar no payload, valide o header x-onnix-signature. Veja verificar assinatura.

Evento recebido

POST https://sualoja.com/webhooks/onnix
Content-Type: application/json
x-onnix-event: charge.paid
x-onnix-event-id: 019e8f0a-1c2d-7aaa-bbbb-0123456789ab
x-onnix-signature: t=1780515992,v1=3a7f...e9d2

{
  "id": "019e8f0a-1c2d-7aaa-bbbb-0123456789ab",
  "type": "charge.paid",
  "created_at": "2026-06-03T19:52:10.200Z",
  "data": {
    "id": "019e8f03-2d48-7f9b-9d8e-eb22404754b2",
    "object": "charge",
    "amount": 2599,
    "currency": "BRL",
    "method": "pix",
    "status": "paid",
    "reference": "pedido-1042",
    "payer": { "name": "MARIA S SOUZA", "document": "12345678909" },
    "payer_request": { "name": "Maria Souza", "document": "12345678909" },
    "txid": "kk6g232xel65a0daee4dd13kk4000637343",
    "end_to_end_id": "E1234567820260603...",
    "paid_at": "2026-06-03T19:52:10.114Z"
  }
}

AnteriorConsultar merchant Próximo Tipos de evento