ZypfyDocs Acessar painel
Webhooks

Webhook: depósito (enviado pela Zypfy ao seu servidor)

POSThttps://seusite.com/webhooks/zypfysua URL de callback (clientCallbackUrl ou a configurada no painel)

Este endpoint é hospedado pelo seu servidor, não pela Zypfy.

A Zypfy faz POST para a URL configurada em clientCallbackUrl (do request de criação do depósito) ou para a URL global configurada no portal quando o status do depósito muda.

Headers que você vai receber

Validando a assinatura

Recompute HMAC_SHA256(secret, "${timestamp}.${corpo_bruto}") sobre o corpo bruto recebido e compare com X-Webhook-Signature em tempo constante. Rejeite timestamps com mais de 5 minutos de diferença. A Webhook Signature fica em Configurações > Credenciais. Veja o guia Verificando a assinatura dos webhooks para exemplos em Node e PHP.

Fluxo de entrega

  1. A Zypfy tenta entregar o webhook quando o status do depósito muda para COMPLETED ou FAILED.
  2. O timeout da requisição é 8 segundos.
  3. Se seu servidor responder 2xx, a entrega é marcada como sucedida.
  4. Não há retry automático agressivo. Se o webhook falhar, você precisa reconciliar chamando GET /api/transactions/deposit com external_id ou end_to_end.

Corpo da requisição

Respostas

200Seu servidor deve responder com 2xx para confirmar recebimento. O corpo da resposta é ignorado pela Zypfy.