Rotacionando Webhook Secrets

O webhook secret é o segredo compartilhado que o DVS usa para assinar com HMAC cada entrega de webhook. Rotacioná-lo periodicamente (ou imediatamente após qualquer suspeita de exposição) é uma boa prática.

Quando rotacionar

Rotação de rotina: a cada 12 meses por política da OSIGU.
Rotação imediata: quando há suspeita de que o secret foi exposto (comitado em um repositório público, vazado em logs, funcionário desligado com acesso).
Iniciada pela OSIGU: quando o monitoramento da OSIGU detecta padrões suspeitos de assinatura ou entrega.

Como funciona a rotação

1Solicitar rotação
Envie e-mail para support@osigu.com com o assunto Webhook secret rotation — <seu tenant slug>. Inclua o motivo e o ID do endpoint de webhook (se disponível).
2OSIGU emite um novo secret
O operador da OSIGU executa o endpoint de admin e envia o novo secret em plaintext por um canal seguro (link de vault no 1Password, e-mail criptografado, entrega presencial — nunca por e-mail simples).
3Período de tolerância de 24 horas
Por 24 horas após a rotação, o DVS continua aceitando verificação de signature com ambos o secret novo e o anterior. Isso evita mensagens perdidas em webhooks em trânsito. Após 24 horas, apenas o novo secret é válido.
4Atualizar o receiver
Atualize a variável de ambiente / secret store com o novo valor. Recomendamos fortemente suportar ambos os secrets simultaneamente durante o período de tolerância.

Padrão de receiver: suportar dois secrets durante a rotação

Este padrão permite trocar de secrets sem perder webhooks. Adicione o secret anterior como fallback por 24 horas e depois remova-o.

Python
Node.js

SECRETS = [
    os.environ["DVS_WEBHOOK_SECRET_CURRENT"],
    os.environ.get("DVS_WEBHOOK_SECRET_PREVIOUS"),  # opcional, somente durante a janela de tolerância
]

def verify_with_any(raw_body, signature_header, timestamp_header):
    for secret in SECRETS:
        if secret and verify_dvs_signature(raw_body, signature_header, timestamp_header, secret):
            return True
    return False

const SECRETS = [
  process.env.DVS_WEBHOOK_SECRET_CURRENT,
  process.env.DVS_WEBHOOK_SECRET_PREVIOUS, // opcional durante a janela de tolerância
].filter(Boolean);

function verifyWithAny(rawBody, signatureHeader, timestampHeader) {
  return SECRETS.some((secret) =>
    verifyDvsSignature(rawBody, signatureHeader, timestampHeader, secret),
  );
}

Após 24 horas, remova DVS_WEBHOOK_SECRET_PREVIOUS do ambiente.

O que o DVS faz durante a rotação

O DVS assina todos os novos webhooks com o secret novo imediatamente.
O hash do secret anterior é mantido por 24h e aceito pelo receiver (desde que o fallback acima esteja implementado).
Após 24 horas, o secret anterior é expurgado do armazenamento do DVS.

O que a rotação NÃO faz

Não altera o URL do webhook.
Não altera o ID do endpoint.
Não pausa a entrega de webhooks — os eventos continuam fluindo.

Perdeu o secret?

Caso o secret não esteja mais disponível (ex.: a única pessoa com acesso saiu da empresa), não é possível recuperá-lo do DVS — os secrets são armazenados com hash bcrypt do nosso lado, nunca em plaintext. Solicite uma rotação; a OSIGU emite um novo.

Quando rotacionar​

Como funciona a rotação​

Padrão de receiver: suportar dois secrets durante a rotação​

O que o DVS faz durante a rotação​

O que a rotação NÃO faz​

Perdeu o secret?​