Configurando webhook

A INFI envia uma notificação HTTP POST ao seu servidor quando o status de uma cobrança ou saque muda. Você pode configurar até 6 URLs, cada uma recebendo categorias específicas de evento (ou tudo).

Diagrama

Cada URL recebe só os eventos que filtra. Múltiplas URLs podem matchar o mesmo evento — todas recebem em paralelo.

Cadastro

No painel da INFI, em Webhooks → Configuração:

Clique em Adicionar webhook.
Informe a URL HTTPS (HTTP é rejeitado — segurança).
Escolha o que essa URL recebe:
- Todos os eventos (catch-all).
- Selecionar categorias: marque uma ou mais entre cashin, cashout, refund, dispute, chargeback. Veja a lista completa em Eventos.
Marque ativo e salve.

Limite: 6 webhooks ativos por conta. Pra mudar, remova um antes de adicionar outro.

Configuração legada (URL única)

Contas criadas antes de maio/2026 podem ter uma URL legada que recebe todos os eventos. Ela continua funcionando como fallback caso nenhum dos webhooks novos matche o evento. Quando configurar URLs por categoria, considere remover a legada (botão “remover” no painel).

Exemplo de configuração: 3 URLs por finalidade

URL 1: https://api.suaempresa.com/webhooks/infi-cashin
       → categoria "cashin"
       → recebe transaction.paid, transaction.failed, transaction.cancelled, transaction.expired

URL 2: https://api.suaempresa.com/webhooks/infi-cashout
       → categoria "cashout"
       → recebe todos os transfer.* (10 eventos)

URL 3: https://api.suaempresa.com/webhooks/infi-refund
       → categoria "refund" + "chargeback"
       → recebe transaction.refunded, transaction.partially_refunded, transaction.chargeback

Cabeçalhos da requisição

Cabeçalho	Descrição
`Content-Type`	`application/json`
`X-Infi-Event`	Nome canônico do evento (ex.: `transaction.paid`).
`X-Infi-Timestamp`	Unix timestamp em segundos, parte da assinatura.
`X-Infi-Signature`	`sha256=<hex>` — HMAC-SHA256. Veja Assinatura.
`X-Infi-Event-Id`	ID único do evento (ex.: `evt_1715000000000_abcdef12`). Mesmo entre URLs do fanout e em reenvios manuais — use para dedupe.

Corpo

{
  "event": "transaction.paid",
  "eventId": "evt_1715000000000_abcdef12",
  "transactionId": "Q4t9aV...",
  "status": "paid",
  "amountCents": 1000,
  "feeCents": 10,
  "netCents": 990,
  "paidAt": "2026-05-06T14:35:12.000Z",
  "timestamp": "1715000000"
}

Campo	Descrição
`event`	Nome canônico do evento. Veja Eventos.
`eventId`	Identificador único do evento. Compartilhado entre URLs do fanout e reenvios manuais — use para dedupe.
`transactionId`	Identifica a transação.
`status`	Novo status. Veja Status.
`amountCents`, `feeCents`, `netCents`	Valores em centavos.
`paidAt`	ISO 8601 UTC quando o status final é `paid`; `null` caso contrário.
`timestamp`	Eco do `X-Infi-Timestamp` para validação cruzada.

Entrega única — sem retry automático

A INFI entrega o webhook em uma única tentativa automática, com timeout de 8 segundos. Se sua aplicação não responder, o evento não é reenviado automaticamente. Estratégia recomendada:

Polling via GET /v1/transactions/:id como fallback para recuperar status.
Reenvio manual pelo painel — toda entrega fica registrada por 60 dias e pode ser disparada de novo. Veja Redespacho.

Resposta esperada

Devolva qualquer 2xx em até 8 segundos.
Faça processamento pesado em background (worker, fila). Acuse recebimento e enfileire.

Próximos

Eventos — lista completa.
Assinatura — como validar.
Retentativa — estratégia de fallback.
Redespacho — como reenviar manualmente uma entrega.

Consultar saldo Eventos