Rotação de secret

Rotacione o secret quando ele vazar, quando alguém com acesso a ele sair da equipe, ou por rotina. A rotação foi desenhada para não exigir sincronia: não existe o momento em que as entregas reprovam porque um lado trocou antes do outro.

Como funciona

curl -X POST https://api.notyfacil.com.br/v1/endpoints/ep_01JB8Y1D6TQ4X8N2VK5HWZ3RFM/rotate-secret \
  -H "Authorization: Bearer $NOTYFACIL_KEY"

{ "id": "ep_01JB8Y1D6TQ4X8N2VK5HWZ3RFM", "secret": "whsec_…", "previousSecretExpiresAt": "2026-09-11T12:00:00Z" }

A partir desse momento, e por 24 horas, toda entrega vai assinada com o secret antigo e o novo, as duas assinaturas lado a lado no mesmo header:

Webhook-Signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= v1,Q1gXh7T0mP2lV8cN4rWjE6yKzA9bU3dF5sH0oLqRtCw=

O receptor que aceita a entrega quando qualquer assinatura confere (como o código de verificação desta documentação faz) continua aceitando com o secret antigo e passa a aceitar com o novo, sem janela de falha.

Em previousSecretExpiresAt, o antigo para de assinar.

O passo a passo

1. Rotacione e guarde o secret novo da resposta. Ele aparece só aí.
2. Entregue o secret novo a quem mantém o receptor.
3. O receptor troca o valor configurado, no ritmo dele, dentro das 24 horas.
4. Dispare um teste do endpoint para confirmar que o receptor aceita.

Vazamento

Se o secret vazou, as 24 horas também valem para quem o tem: por esse tempo, as entregas continuam saindo assinadas com ele. O que protege o receptor nessa janela é o timestamp (assinatura com mais de 5 minutos é recusada) e trocar o valor do lado dele logo em seguida, sem esperar a janela.

Rotacionar de novo dentro da janela

Uma segunda rotação dentro das 24 horas encurta a validade de todos os secrets anteriores para 24 horas a partir dela. Nunca há mais de uma janela aberta.

Referência: rotacionar o secret