Problemas comuns

Para: Dev — Conferido em 2026-10-18.

Esta página lista os sintomas mais comuns de uma integração de webhooks, a causa provável e o que fazer. No fim há o que reunir antes de chamar o suporte: Dracma-Event-Id e operation_id.

O que é

O Dracma não envia nenhum header de rastreamento (traceparent) ao seu receptor, e o id interno de trace não sai da casa. A correlação entre o que você viu e o que o Dracma registrou é feita pelo Dracma-Event-Id (igual ao id do corpo) e pelo operation_id. Registre os dois em todo log do receptor. Quando a assinatura falhar, registre o Dracma-Event-Id do header, sem interpretar o corpo.

Quando usar

Use esta página quando um evento não chegar, chegar duplicado, for recusado pelo seu receptor ou aparecer na DLQ. Para cada caso, o log de entregas e a aba de DLQ do painel (Webhooks no painel) mostram as tentativas, o status HTTP, a duração e o erro resumido (até 200 caracteres) de cada uma.

Como funciona

Siga a ordem: (1) o evento existe? (GET /events), (2) o Dracma tentou enviar? (log de entregas), (3) o que o seu receptor respondeu? (status e erro da tentativa), (4) o que o seu receptor fez com a resposta? (seu log).

O evento não chegou

Sintoma Causa provável O que fazer
Nenhum webhook, nem de teste A URL ainda não está efetiva: o pedido de cadastro espera a aprovação de outra pessoa e as 24 h seguintes. Confira o pedido em Webhooks no painel.
Nenhum webhook; entregas skipped com no_endpoint Os eventos nasceram antes de a URL estar cadastrada. Eles não são enviados depois. Recupere por GET /events.
Entregas skipped com event_not_subscribed O tipo do evento não está na sua assinatura. Inclua o tipo na assinatura (lista vazia = todos) e use o job de GET /events para o passado.
Entregas skipped com environment_mismatch O evento é de teste e a URL cadastrada é a da operação real, ou o inverso. Cadastre a URL certa em cada operação.
Fora de produção, o painel recusa a URL O domínio não é de teste e não foi liberado. Peça a liberação do domínio no onboarding. Túneis temporários não funcionam. Veja Seu endpoint.
Tentativas falham sem código HTTP e sem erro do seu servidor Não há segredo de webhook ativo, o nome resolve para IP bloqueado, o certificado TLS é inválido ou a porta 443 não responde. Rotacione o primeiro segredo; confira DNS, certificado e firewall.
Evento do tipo rules.updated esperado Esse evento não existe. Veja Catálogo de eventos.

O seu receptor recusa o evento

Sintoma Causa provável O que fazer
401 em todos os eventos Segredo errado (por exemplo, o da operação de teste usado na real: cada operação tem o seu), segredo trocado numa rotação ou relógio do servidor fora de sincronia. Confira o segredo da operação certa; mantenha a lista de segredos; sincronize o NTP. Veja Segredo e rotação.
401 só em alguns eventos Receptor testa só o primeiro v1 durante uma rotação. Teste todos os pares v1 × segredo.
401 mesmo com o segredo certo O corpo foi reserializado ou alterado por proxy, framework ou compressão antes da verificação. Verifique sobre os bytes crus. Teste com os vetores de Requisição e assinatura.
401 só nas reentregas Relógio fora de sincronia (janela de 300 s sobre o t= da tentativa). Sincronize o NTP.
400 "id difere" O seu código compara o Dracma-Event-Id com um campo errado, ou um proxy reescreveu o header. O header é igual ao id do corpo.
Redirect (301/302) A URL cadastrada redireciona (http para https, barra final, www). O Dracma não segue redirect: cadastre a URL final.

Chegou, mas o resultado está errado

Sintoma Causa provável O que fazer
O mesmo evento chega duas vezes Esperado (at-least-once), ou o seu receptor demorou mais de 10 s e respondeu depois do corte. Deduplique por Dracma-Event-Id; responda rápido e processe em fila.
deposit.paid antes de deposit.pending Esperado: não há ordem entre eventos. Aja pelo estado da consulta e por object_version.
O fetch-back devolve 404 A chave de API é de outra operação (teste × real) ou o evento é forjado. Use a chave da operação do evento (operation_id). Não credite.
O data.object está "velho" numa reentrega O corpo é congelado no momento da transição. Use o estado da consulta.
O jogador pagou, mas não houve webhook Pode ter ido para a DLQ ou ficado skipped; o pagamento pode ter chegado depois da expiração. Consulte o depósito e GET /events; veja Catálogo de eventos.
O receptor responde 4xx de propósito para "rejeitar" O Dracma repete 4xx por até 72 h. Para um evento que você não quer tratar, responda 200.

Entregas na DLQ

Um evento na DLQ esgotou 15 ou 16 tentativas em até 72 h. Corrija a causa, reentregue pelo painel (a reentrega mantém o Dracma-Event-Id) e confirme com o job de GET /events que não ficou lacuna. Veja Retentativas, skipped e DLQ.

Exemplos

O que reunir antes de chamar o suporte

Envie, no canal de suporte informado no onboarding:

Dado De onde
Dracma-Event-Id do evento (evt_…) Header ou campo id do corpo; log do receptor.
operation_id Campo do corpo; tela da operação no painel.
Horário (UTC) e fuso da sua leitura Log do receptor.
Status HTTP e erro da última tentativa Log de entregas do painel.
O object_id (dep_… ou wdr_…) e o external_id Corpo do evento.
O que o seu receptor respondeu e o que ele fez Log do receptor.

Nunca envie o segredo de webhook, o segredo de chamada ou a assinatura completa. Se precisar mostrar uma assinatura, mostre só os primeiros 8 caracteres do v1.

Verificação mínima de um evento

# Com o script assinar.sh dos exemplos executáveis ($DRACMA_BASE_URL inclui /v1):
# 1. O evento existe para a sua operação?
./assinar.sh GET '/events?object_id=dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d'

# 2. Qual o estado atual do objeto?
./assinar.sh GET /deposits/dep_0198b7c24d5e7a1b8c2d3e4f5a6b7c8d

Erros e casos de borda

  • Alerta de URL falhando: o painel marca a saúde da URL como "falhando" quando a última tentativa não foi 2xx e a primeira falha desde o último 2xx tem pelo menos 15 minutos.
  • Muitos erros ao mesmo tempo: uma rajada de 4xx do seu receptor gera um volume grande de reentregas nas horas seguintes. Corrija o receptor primeiro; as tentativas pendentes vão se acomodando sozinhas.
  • Teste no sandbox: para provar o receptor, gere um depósito de teste, simule o pagamento e reentregue o evento; veja Sandbox.
  • Ainda sem causa: abra um chamado no canal de suporte com os dados acima (Suporte).

Veja também