Seu endpoint

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

O Dracma só envia webhooks para a URL que você cadastra na operação, e só se ela passar na política de URL: HTTPS na porta 443, nome de domínio público, sem credencial na URL e sem redirect. Esta página lista as regras, explica o que acontece quando um endereço é recusado e diz como liberar um domínio fora de produção.

O que é

Cada operação tem uma URL de webhook. A política abaixo vale no cadastro e é conferida de novo antes de cada tentativa de entrega.

Regra Detalhe
Esquema Somente https. http é recusado.
Porta 443. Uma porta explícita diferente de 443 é recusada (:443 explícito é aceito).
Credenciais Sem usuário nem senha na URL (https://usuario:senha@host/... é recusado).
Fragmento Sem #fragmento.
Tamanho Até 2048 caracteres, tanto como você digitou quanto depois de normalizada.
Nome do host Nome DNS em ASCII (domínios internacionais em xn--), com pelo menos dois rótulos de 1 a 63 caracteres, sem hífen nas pontas, até 253 caracteres no total. Sublinhado não é aceito.
Nomes numéricos O último rótulo não pode ser numérico (127.1, 0x7f.0.0.1 e 2130706433 são recusados).
localhost localhost e *.localhost são recusados.
IP literal Endereços em faixa não pública são recusados. Prefira sempre um nome de domínio: o certificado TLS costuma ser emitido para nomes.
Redirect O Dracma não segue redirect. Um 3xx conta como falha. Cadastre a URL final.

Certificado

O Dracma valida o certificado do seu servidor como um navegador: cadeia completa de uma autoridade pública e nome do host no certificado. Certificado autoassinado, vencido ou com cadeia incompleta faz a tentativa falhar.

Quando usar

Leia esta página antes de pedir a primeira URL e sempre que mudar o endereço do receptor (novo domínio, novo balanceador, migração de provedor).

Quem cadastra e como

No onboarding, o Dracma cria o seu tenant e convida o administrador da sua empresa por e-mail (inclusive no ambiente de homologação, com e-mail real). Esse administrador aceita o convite, torna-se o dono do tenant e, a partir daí, cria as próprias operações e chaves. Veja Do zero ao go-live.

A URL é cadastrada de duas formas:

  1. Na criação da operação, quando o dono do tenant cria a operação e informa a URL. A política acima vale do mesmo jeito.
  2. Pelo painel, na tela de webhooks (Webhooks no painel): você propõe a URL e os tipos de evento, o painel valida a política (inclusive a resolução de DNS) sem gravar nada e abre um pedido. Outra pessoa com permissão de gerenciar webhooks precisa aprovar, e a mudança só passa a valer 24 horas depois da aprovação. Quem propõe confirma a identidade de novo no painel (verificação adicional) antes de enviar.

Enquanto a mudança espera, a URL anterior (se houver) continua valendo.

Testar a URL

Não disponível

O Dracma não prova que a URL é sua. Não existe ping, desafio (challenge) nem verificação de posse no cadastro: a validação só confere forma, política e DNS. Por isso um erro de digitação em um domínio que existe passa no cadastro, e os eventos seguem para o endereço errado até alguém notar.

Para testar o receptor de verdade, use a operação de teste: gere um depósito, simule o pagamento e peça a reentrega do evento (veja Sandbox). O endereço de teste não substitui conferir, no painel, o log de entregas depois do primeiro evento real.

Como funciona

flowchart TD A[URL cadastrada] --> B{Forma válida?<br/>https, 443, sem credencial} B -- não --> X[Recusada] B -- sim --> C{Host permitido neste ambiente?} C -- não --> X C -- sim --> D[Resolve o DNS] D --> E{Algum IP em faixa proibida?} E -- sim --> X E -- não --> F[Envia o POST] F --> G{2xx em até 10 s?} G -- sim --> H[Entregue] G -- não --> I[Nova tentativa pelo cronograma]

Proteção contra acesso a redes internas

O Dracma resolve o nome do seu host no cadastro e antes de cada tentativa, e confere o endereço efetivamente usado na conexão. Se qualquer endereço resolvido cair em uma faixa que não é da internet pública, a tentativa falha. Ficam bloqueadas, entre outras: redes privadas (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback, link-local (inclusive o endereço de metadados de nuvem), CGNAT (100.64.0.0/10), faixas reservadas, de documentação e de multicast. No IPv6, só endereços de unicast global (2000::/3) passam.

Consequência prática: o seu receptor precisa estar em um IP público roteável, atrás de um nome DNS estável. Se o nome passar a resolver para um endereço interno (por exemplo, um DNS de split-horizon), o cadastro já foi aceito, mas cada tentativa falha e o evento percorre o cronograma até a DLQ. Uma falha desse tipo aparece no log de entregas como erro sem código HTTP.

Ambiente da URL

O ambiente da URL é o da operação: sandbox (operação de teste) ou production (operação real). Ele não muda depois de criado. Cada evento nasce em um ambiente, e só é enviado à URL da operação do mesmo ambiente. Se os ambientes divergem, a entrega fica skipped com o motivo environment_mismatch e nada sai. Isso impede que um evento de teste chegue ao receptor de produção, e o inverso. Veja Retentativas, skipped e DLQ.

Hosts permitidos fora de produção

Nas instâncias do Dracma que não são a de produção (como a de homologação), o Dracma só envia webhooks para hosts de teste, mesmo que a operação seja real. Passam:

  • nomes sob os domínios reservados .test, .invalid e .example;
  • os domínios que o Dracma tiver liberado para você.

Qualquer outro domínio é recusado no cadastro (o painel aponta o campo url) e, se já estiver cadastrado, a tentativa falha. Isso existe para que o ambiente de testes nunca dispare efeito em um sistema real por engano.

Os domínios reservados não existem na internet pública, e o nome cadastrado também precisa resolver no DNS a partir do Dracma. Na prática, para receber webhooks de verdade fora de produção, você precisa que o seu domínio real seja liberado.

Para receber webhooks de teste no seu domínio real, peça a liberação no onboarding: informe ao Dracma o domínio (ou o sufixo) que você quer usar fora de produção. A liberação é feita pelo Dracma; você não consegue ativá-la sozinho.

Não disponível

Túneis públicos temporários (do tipo ngrok, localtunnel e semelhantes) e localhost não funcionam como destino de webhook fora de produção: o domínio do túnel não é um host de teste e não está liberado, e localhost é recusado pela política. Para desenvolver o receptor sem expor a máquina, simule a requisição com os vetores e as receitas do sandbox.

Exemplos

URL Resultado
https://pagamentos.operador.example/dracma/webhook Passa na política em qualquer instância (domínio reservado .example); o nome ainda precisa resolver no DNS.
https://pagamentos.operador.example:443/dracma/webhook Passa na política (porta 443 explícita).
https://pagamentos.operador.example:8443/dracma/webhook Recusada: porta diferente de 443.
http://pagamentos.operador.example/dracma/webhook Recusada: não é HTTPS.
https://usuario:senha@pagamentos.operador.example/webhook Recusada: credenciais na URL.
https://pagamentos.operador.example/webhook#x Recusada: fragmento.
https://localhost/webhook Recusada: localhost.
https://10.0.0.5/webhook Recusada: IP de rede privada.
https://127.1/webhook Recusada: nome numérico.
https://pagamentos.operador.com.br/dracma/webhook Aceita em produção; fora de produção só se o domínio tiver sido liberado.

Erros e casos de borda

Sintoma Causa provável O que fazer
O painel recusa o pedido apontando o campo url A política acima (esquema, porta, credencial, host) ou o DNS do nome resolve para faixa bloqueada, ou o domínio não é de teste fora de produção. Corrija a URL. Em instância que não é a de produção, peça a liberação do domínio no onboarding.
A URL foi aceita, mas as entregas falham sem código HTTP O nome passou a resolver para um IP bloqueado, o certificado é inválido ou o servidor não responde na porta 443. Confira DNS, certificado e firewall. O log de entregas mostra o erro de cada tentativa.
Entregas ficam skipped com environment_mismatch O evento é de teste e a URL cadastrada é a da operação real (ou o inverso). Cada operação tem a própria URL; cadastre a certa na operação certa.
Mudança de URL "não pega" O pedido ainda espera aprovação de outra pessoa ou as 24 h depois da aprovação. Veja Webhooks no painel.
O receptor está atrás de uma lista de IPs permitidos O Dracma não publica endereços de saída fixos. Veja o aviso abaixo.

IPs de saída do Dracma

Não disponível

O Dracma não publica uma lista de endereços IP de saída dos webhooks: ela não está no painel nem em nenhuma rota da API, e o Dracma não garante IP fixo de origem. Textos antigos diziam que a lista estava "disponível no painel"; isso não é verdade. Não construa seu receptor dependendo de filtrar pelo IP de origem.

A defesa do receptor é a assinatura sobre o corpo cru e o fetch-back autenticado, que valem de qualquer IP. Se a sua política de segurança exige uma lista de origens, hoje não há como atendê-la: o Dracma não oferece essa lista. Se um dia você receber uma lista por contrato, trate-a como uma camada a mais, que nunca substitui a verificação da assinatura. Dentro do seu serviço, confie em X-Forwarded-For somente quando o salto anterior for o seu proxy de borda.

Veja também