Principal Integração e API Como receber e validar webhooks da Dotfy?

Como receber e validar webhooks da Dotfy?

Última atualização em Nov 10, 2026

O webhook é um POST assinado que a Dotfy envia à sua URL a cada acontecimento. O comprador pode fechar a página antes de voltar ao seu site, e o webhook chega mesmo assim.

Cadastre um endpoint

Faça POST /api/webhook-endpoints com name, url e events. A URL precisa ser HTTPS e alcançável pela internet. A conta aceita até 10 endpoints.

A resposta traz o secret, que só aparece nesse momento. Se perder, rotacione. O segredo antigo para de valer no mesmo instante.

Valide a assinatura

O cabeçalho X-Webhook-Signature vem no formato t=<epoch_ms>,v1=<hmac_sha256_hex>.

  1. Calcule HMAC-SHA256(secret, "<t>.<corpo bruto>").
  2. Compare o resultado com v1 em tempo constante.
  3. Recuse o que estiver a mais de 5 minutos de t.

Dois erros comuns: t está em milissegundos, não em segundos. E a assinatura usa o corpo cru, antes de qualquer parse.

Responda rápido

Responda qualquer 2xx em até 15 segundos. Fora disso, a entrega é reagendada. São cinco tentativas no total: na hora do evento, 60 segundos depois, 5 minutos depois, 15 minutos depois e 1 hora depois. Depois da quinta tentativa, a entrega fica FAILED e não é retomada sozinha.

  • Responda primeiro, processe depois. Grave o evento numa fila e devolva 200.
  • Seja idempotente por X-Webhook-ID. A mesma entrega pode chegar mais de uma vez.

Principais eventos

  • EVENT:CHARGE_PAID: PIX ou boleto confirmado. É o sinal para entregar.
  • EVENT:CHARGE_CREATED e EVENT:CHARGE_EXPIRED. Estorno de PIX chega como EVENT:CHARGE_EXPIRED.
  • EVENT:INTERNATIONAL_PAID e EVENT:INTERNATIONAL_REVERSED: venda internacional, de cartão ou de carteira digital.
  • EVENT:DISPUTE_OPENED, _WON, _LOST e _CANCELED: MED e disputas.
  • EVENT:WITHDRAWAL_COMPLETED e EVENT:WITHDRAWAL_FAILED: saques.
  • EVENT:SPLIT_RECEIVED: chega no endpoint de quem recebe a parte.
  • EVENT:RECURRENCE_*: Pix Automático.

Venda internacional expirada, recusada ou bloqueada não gera webhook. Consulte a API nesses casos.

Não recebeu a notificação de uma cobrança? O histórico de entregas por cobrança mostra o evento, o endpoint e o status que o seu servidor respondeu. Os 25 eventos estão no Catálogo de eventos.