Webhooks no painel¶

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

A tela Webhooks é onde você configura o endereço que recebe os eventos da operação, gira o segredo de assinatura, acompanha as entregas e trata os eventos que esgotaram as tentativas. Ela tem quatro abas: Configuração, Entregas, DLQ e Saúde. O formato dos eventos e a verificação da assinatura estão na seção Webhooks.

O que é¶

A configuração de webhook é feita só pelo painel: não existe API pública para cadastrar ou alterar a URL, os eventos ou o segredo. Cada operação tem um endereço de webhook.

Quem vê e quem gere:

Quem só vê não enxerga o formulário de proposta, o botão de rotação nem a seleção da DLQ.

As quatro abas:

Quando usar¶

• No go-live de cada operação: informar a URL, escolher os eventos e gerar o primeiro segredo.
• Quando o receptor muda de endereço ou de ambiente.
• Para investigar por que um evento não chegou: Entregas e Saúde.
• Depois de uma indisponibilidade do receptor: DLQ.

Como fazer¶

Aba Configuração¶

A aba mostra:

• Destino: a URL cadastrada (ou "Não configurada"), o ambiente (Sandbox ou Produção) e a marca HTTPS obrigatório nas operações Reais.
• Eventos assinados: a lista dos tipos escolhidos, ou "Todos os eventos" quando nenhum foi marcado.
• Segredo de assinatura: a situação (Nenhum segredo, Ativo ou Em rotação (duas assinaturas v1=)) e a tabela de segredos vigentes com identificador, data de criação, data de expiração e estado. O valor do segredo nunca é exibido.
• Pedidos de alteração (só para o Administrador): os pedidos recentes, com votos e a espera restante.

O catálogo de eventos que você pode assinar tem 17 tipos:

Veja o conteúdo de cada um em Catálogo de eventos.

Mudar a URL ou os eventos¶

1. Na aba Configuração, em Propor alteração, informe a URL de destino (até 2048 caracteres) e marque os tipos de evento. Sem nenhum marcado, a operação recebe todos.
2. Escreva o motivo (de 10 a 1000 caracteres) e clique em Propor alteração. É preciso confirmação recente.
3. Antes de abrir o pedido, o Dracma simula a alteração: valida o formato da URL e a política de destino (a mesma que vale nas entregas). Uma URL recusada nessa simulação não gera pedido. Veja Seu endpoint.
4. Outro Administrador aprova ou recusa o pedido, com motivo. Quem propôs não vota.
5. Aprovado, o pedido fica Aprovado, no time-lock e a alteração só vigora 24 horas depois. Qualquer Administrador pode cancelar nesse intervalo.

Regras da URL:

• A URL deve ser https://. Em operação Real isso é obrigatório e a tela mostra a marca HTTPS obrigatório.
• Sem usuário e senha na URL e sem trecho #.
• Os eventos precisam estar no catálogo, sem repetição.

O primeiro endereço pode entrar de duas formas:

• informado no formulário de criação da operação: o Dracma o cadastra em segundo plano, sem pedido e sem espera (veja Tenants e operações);
• proposto nesta aba, quando a operação nasceu sem URL: segue o fluxo acima, com aprovação e 24 horas.

Planeje o go-live com esse prazo.

Girar o segredo¶

• O botão Rotacionar segredo só aparece quando a operação já tem URL cadastrada. O primeiro segredo só nasce por esse botão: cadastrar a URL não cria segredo.
• Uma pessoa basta, com confirmação recente. Não há aprovação nem espera.
• O segredo novo aparece uma vez, num campo para copiar, com o identificador e "sobreposição de 7 dias". Recarregar a tela o apaga.
• Durante 7 dias a entrega leva duas assinaturas v1=: a do segredo antigo e a do novo. Troque o segredo no receptor nesse período.
• Não existe "revogar o segredo antigo" no painel. Uma segunda rotação encerra a sobreposição. Veja Segredo e rotação.

Aba Entregas¶

A aba lista as entregas da operação, da mais recente para a mais antiga (50 por vez). Filtros:

• Status: Pendente, Entregue, DLQ ou Ignorado. Quando uma entrega é ignorada, o motivo aparece abaixo do status.
• Tipo de evento: qualquer um dos 17 do catálogo.

Colunas: o evento (clique para abrir o detalhe), o tipo, o status, o número de tentativas, o último código HTTP, a latência da última tentativa e a próxima tentativa.

O detalhe de uma entrega mostra o evento, o status e a tabela de tentativas em ordem: número, horário (Brasília), código HTTP, latência em milissegundos e o erro, quando houve. O último erro tem no máximo 200 caracteres.

Aba DLQ¶

A DLQ guarda os eventos que esgotaram as tentativas de entrega (72 horas sem resposta 2xx). Nenhum evento é perdido: ele continua disponível para reentrega e em GET /v1/events. A aba mostra até 100 eventos, incluindo os já resolvidos, com o evento, o tipo, o número de tentativas, o último HTTP e a situação (Na DLQ ou Resolvido em … com o motivo).

Reentregar:

1. Marque os eventos (até 50 por vez).
2. Clique em Prévia. A tela mostra o destino (URL e ambiente) e os eventos; nada é enviado ainda. Eventos que não estão na DLQ aparecem em "Não encontrados na DLQ".
3. Clique em Reentregar. Cada evento é reenviado com o mesmo Dracma-Event-Id, com uma nova janela de 72 horas, e o resultado vem por evento: Reagendado, Não encontrado ou Falhou.

Marcar como resolvido:

1. Marque os eventos e escreva o motivo (de 10 a 1000 caracteres): por exemplo, "tratado manualmente pelo ticket 123".
2. Clique em Marcar como resolvido. O evento sai da fila de pendentes e fica registrado com o motivo.

Reentregar e resolver não pedem aprovação nem confirmação recente; ficam na Auditoria com o autor.

Aba Saúde¶

A aba mostra uma tabela com as últimas 24 horas, hora a hora (horário de Brasília): tentativas, quantas deram 2xx e a taxa. No alto:

• "Sem falha contínua na URL." quando está tudo bem;
• um alerta em vermelho quando a URL falha há 15 minutos ou mais, com a hora da última tentativa e do último sucesso.

Testar a URL (só Teste)¶

Na aba Entregas de uma operação de Teste, o Administrador vê Testar a URL (sandbox): informe o identificador de um evento que já existe e o Dracma o reenvia para a sua URL, com o mesmo Dracma-Event-Id.

Não existe um evento sintético de teste. Para testar, gere um depósito e simule o pagamento (veja Cobrança de teste) e use o evento resultante.

Exemplos¶

Cronograma de uma mudança de URL, com dois Administradores (Ana e Bruno), horários de Brasília:

Depois de uma queda do receptor que gerou eventos na DLQ:

1. Na aba Saúde, confirme que a URL voltou a responder.
2. Na aba DLQ, marque os eventos, clique em Prévia e depois em Reentregar.
3. Confira o resultado Reagendado de cada evento e acompanhe em Entregas.

Erros e casos de borda¶

Casos de borda:

• Segredo vazado. O painel não revoga o segredo antigo na hora. Gire o segredo duas vezes seguidas para encerrar a sobreposição e confira os eventos com a busca em GET /v1/events, que não depende do webhook. Veja Segredos e vazamento.
• Lista de IPs de saída do Dracma. Não disponível: o Dracma não publica essa lista, no painel nem em outro lugar, e não garante IP fixo de origem. Não filtre a rota do webhook por IP; veja Seu endpoint.
• Operação nova sem segredo. É esperado: o primeiro segredo só existe depois de Rotacionar segredo.

Veja também¶

• Webhooks
• Receptor passo a passo
• Retentativas, skipped e DLQ
• Alertas e e-mails
• Chaves de API