Webhooks

O sistema de webhooks da Saq envia notificações em tempo real sobre mudanças de status das suas transações. Quando você cria uma transação e fornece um callbackUrl, nosso sistema envia atualizações para essa URL toda vez que houver mudança de status.

O que é um webhook (callback)

Um webhook (também chamado de callback) é uma requisição POST que a Saq envia para o seu servidor quando algo acontece. Ao contrário da API normal (onde você chama a Saq), aqui é o oposto: a Saq chama você.

Pensa numa cobrança Pix. Você criou ela, exibiu o QR ao cliente, e agora precisa saber quando o cliente paga. Duas opções:

1. Polling, ficar perguntando a cada X segundos "já pagou? já pagou?" (custoso, lento, desnecessário).
2. Webhook, deixar a Saq te avisar assim que o pagamento entrar (instantâneo, eficiente, recomendado).

Como configurar

Não existe endpoint separado para "cadastrar webhook". A URL é informada a cada transação criada, no campo callbackUrl do body:

{
  "amount": 99.90,
  "callbackUrl": "https://seusite.com.br/webhooks/saq",
  "clientReference": "pedido-2025-001"
}

A Saq vai enviar o callback para essa URL toda vez que aquela transação mudar de status (PENDING → COMPLETED, COMPLETED → REFUNDED, etc).

Sistema de retry

Os webhooks da Saq têm um sistema robusto de retentativa que garante a entrega mesmo em falhas temporárias. A Saq reenvia até 72 vezes o mesmo callback com backoff exponencial e jitter, distribuindo melhor a carga e evitando picos de requisições.

Segurança

Para garantir integridade e segurança, restrinja o acesso ao seu endpoint de webhook. Solicite o IP oficial da Saq ao suporte e aceite callbacks apenas dessa origem.

Campos do payload

Identificação

Status e valores

Cobrança gerada (depósito)

Pagador

Recebedor

Saque via chave Pix

Liquidação e estorno

Timestamps

Infração (disputa Pix)

Boas práticas

• Responda rápido: devolva 2xx em menos de 5s. Processe pesado em fila/worker, não no handler.
• Idempotência: armazene id + status para deduplicar. O mesmo callback pode chegar mais de uma vez (retentativa, mudanças sucessivas).
• Use clientReference: passe um identificador externo na criação da transação. Volta no callback e facilita correlacionar com seu pedido.
• Restrinja por IP: aceite callbacks apenas do IP oficial da Saq.

Inspeção e reenvio

A API expõe a lista completa de callbacks enviados:

• GET /user/callbacks, lista paginada
• GET /user/callbacks/{id}, detalhes
• POST /user/callbacks/resend/{transactionId}, reenviar callback de uma transação
• POST /user/callbacks/resend, reenvio em lote