Pular para o conteúdo principal
Webhooks permitem que sua aplicação seja notificada automaticamente quando ocorrerem mudanças em payments e cashouts.

​
Como funciona

Ao criar um payment ou um cashout com callbackUrl, a Safefy envia uma requisição HTTP POST para essa URL sempre que o status muda para um estado relevante. Para payloads completos por domínio, veja:

​
Eventos de payment

EventoDescriçãoQuando acontece
payment.completedPagamento confirmadoQuando o PIX é pago e confirmado pelo banco
payment.expiredTransação expirouQuando o prazo para pagamento esgota
payment.failedFalha no processamentoQuando ocorre erro na adquirente ou validação
payment.cancelledPagamento canceladoQuando o pagamento é cancelado manualmente
payment.refundedEstorno totalQuando um pagamento confirmado é estornado
payment.partially_refundedEstorno parcialQuando parte do pagamento é estornada
payment.refund_requestedEstorno solicitadoQuando o estorno entra em processamento

​
Eventos de cashout

EventoStatus do saque
cashout.completedCompleted
cashout.failedFailed
cashout.rejectedRejected
cashout.cancelledCancelled

​
Headers enviados

HeaderDescrição
X-Safefy-SignatureAssinatura HMAC-SHA256 para validação
X-Safefy-EventTipo do evento (payment.* ou cashout.*)
X-Safefy-DeliveryID único da entrega
X-Safefy-AttemptNúmero da tentativa (1, 2, 3)

​
Assinatura

  • Para eventos payment.*, o segredo é o paymentId.
  • Para eventos cashout.*, o segredo é o payoutId.
Sempre valide a assinatura antes de processar o webhook.

​
Retries

Se sua aplicação não responder com 2xx, a Safefy tenta novamente:
  1. Tentativa 1 (imediata)
  2. Tentativa 2 após ~2 segundos
  3. Tentativa 3 após ~4 segundos
Recomendação: confirme rápido (200 OK) e processe em background.

​
Idempotência

Como podem existir retries, trate o processamento como idempotente.
  • Chave recomendada: id (delivery id) ou data.id + type
  • Ignore eventos já processados para evitar duplicidade

​
Exemplo rápido

{
  "id": "4d955fd7-cbb9-4d3c-8d36-4cb5de773b35",
  "type": "cashout.completed",
  "createdAt": "2026-02-25T12:00:00Z",
  "data": {
    "id": "8f8fce31-5c83-42c4-b90b-c29636b595e3",
    "status": "Completed",
    "amount": 50000,
    "netAmount": 49000
  }
}

​
Fluxo de status de payment

Entenda o ciclo de vida de uma transação e quando cada webhook é disparado:
TentativaIntervalo
1Imediato
22 segundos
34 segundos

​
Boas praticas

Responda rápido

Retorne 200 OK imediatamente e processe o webhook de forma assíncrona.

Seja idempotente

Use o id do webhook para evitar processar o mesmo evento duas vezes.

Valide a assinatura

Sempre verifique X-Safefy-Signature antes de confiar no payload.

Use HTTPS

Configure sua callbackUrl apenas com HTTPS em produção.