Segredo e rotação¶

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

O segredo de webhook (whsec_…) é a chave com que o Dracma assina cada entrega e com que o seu receptor a verifica. O primeiro segredo só existe depois que você clica em "Rotacionar segredo" no painel. A rotação mantém o segredo anterior por 7 dias, e "revogar" um segredo vazado é, na prática, rotacionar duas vezes.

O que é¶

O segredo de webhook é outro segredo, diferente do segredo de chamada da API (sk_…). Guarde os dois no cofre, cada um separado, e nunca no navegador nem em código de frontend.

Quando usar¶

O primeiro segredo¶

Sem segredo ativo, o Dracma não envia a entrega: a tentativa falha antes de sair, e o evento percorre o cronograma até a DLQ. Por isso:

1. Cadastre a URL (Seu endpoint).
2. Rotacione o segredo, copie o valor na hora e guarde-o no cofre do receptor.
3. Só então gere eventos.

Rotação¶

A rotação exige:

• permissão de gerenciar webhooks na operação;
• confirmação de identidade adicional no painel (step-up);
• uma pessoa: diferente da mudança de URL, a rotação não precisa de aprovação de uma segunda pessoa nem de espera.

A rotação vale imediatamente. Todas as ações ficam na trilha de auditoria do painel, sem o valor do segredo.

Como funciona¶

Sobreposição de 7 dias¶

Quando você rotaciona:

• o segredo novo passa a assinar imediatamente;
• o segredo que era o mais novo até agora vira o anterior e continua assinando por 7 dias; depois ele expira;
• qualquer segredo mais antigo que o anterior expira na hora.

Enquanto os dois valem, cada entrega leva dois v1, o do segredo novo primeiro. O seu receptor mantém uma lista de segredos ativos (1 ou 2 itens) e aceita se qualquer v1 bater com qualquer segredo da lista, em tempo constante e sem sair do laço no primeiro acerto.

Procedimento sem perder entrega¶

1. Rotacione no painel e copie o whsec_ novo.
2. Adicione o segredo novo à lista do receptor pelo cofre ou pelo pipeline de deploy, nunca à mão no servidor. O receptor passa a aceitar os dois.
3. Confirme que os webhooks continuam sendo aceitos (o log de entregas do painel mostra 2xx).
4. Remova o segredo anterior da lista do receptor, depois de confirmar. O Dracma continua enviando dois v1 até o anterior expirar; o receptor com um segredo só ignora o v1 que não conhece.

Você pode inverter os passos 2 e 3 sem risco: o receptor que só conhece o segredo novo aceita o 1º v1, e o que ainda só conhece o anterior aceita o 2º. Foi pensado para que a rotação nunca derrube a integração.

Quando rotacionar¶

Rotacione também quando alguém que conhecia o segredo sair do projeto e sempre que houver suspeita de vazamento.

Exemplos¶

Linha do tempo de um segredo, com duas rotações seguidas (S1 é o segredo original):

Estados que o painel mostra para cada segredo: o mais novo está active; um segredo anterior com data de expiração futura está expiring (a operação fica em "rotação" enquanto houver um). Segredos vencidos deixam de aparecer.

Erros e casos de borda¶

Segredo vazado: "revogar" é rotacionar duas vezes¶

O que protege o seu dinheiro quando o segredo vaza:

1. O fetch-back. Quem tem o segredo consegue forjar um webhook com assinatura válida, mas o seu receptor só credita pelo estado que a API devolve para a sua credencial. Um webhook forjado não cria dinheiro. Veja Receptor passo a passo.
2. A sua lista de segredos. O que decide se um webhook é aceito é a lista do seu receptor, não o relógio do Dracma.

Procedimento de emergência, nesta ordem:

1. Rotacione no painel e obtenha o segredo novo. Como explicado acima, o segredo vazado continua assinando no Dracma por 7 dias; isso é irrelevante para a segurança, porque o que importa é o que o seu receptor aceita.
2. Troque a lista do receptor: coloque o segredo novo e remova imediatamente o vazado. A partir daqui, nenhum webhook assinado só com o segredo vazado é aceito.
3. Rotacione uma segunda vez se quiser que o Dracma pare de assinar com o segredo vazado agora: a 2ª rotação expira na hora o segredo mais antigo e deixa o anterior por mais 7 dias. Adicione o segredo da 2ª rotação ao receptor.
4. Procure forjados: compare os eventos que o seu receptor processou com GET /events e com a reconciliação (Recuperação com GET /events).
5. Descubra a origem do vazamento (log, repositório, ferramenta de suporte) e corrija.

O passo 2 é o que fecha a janela de aceitação; o passo 1 sozinho não basta.

Outros casos¶

Veja também¶

• Requisição e assinatura: como o segredo entra no HMAC.
• Receptor passo a passo: lista de segredos e fetch-back.
• Webhooks no painel: a tela de rotação.
• Segredos e vazamento: política geral de segredos.