Como faço para rotacionar um segredo de webhook sem downtime?

Seus receptores podem ser implantados em momentos diferentes. Uma sobreposição permite que um receptor usando o segredo antigo e um receptor usando o novo segredo autentiquem a mesma entrega.

Continue verificando as entregas durante toda a implantação para que uma solicitação de um invasor não dispare processamento.

O que acontece quando eu rotaciono?

Bird fornece um novo segredo de assinatura. Implante-o em até 24 horas, enquanto Bird ainda assina com o segredo antigo.

Chame rotateWebhookSecret para o seu endpoint. Salve o secret, uma string não vazia que começa com whsec_, porque ele é retornado apenas nessa resposta.

Bird assina cada entrega com ambos os segredos durante a sobreposição. O cabeçalho webhook-signature contém assinaturas separadas por espaço, cada uma começando com v1,.

Um receptor pode verificar qualquer uma das assinaturas usando o segredo correspondente. Conclua a implantação em até 24 horas porque o segredo antigo para de assinar após essa janela.

O que o meu handler precisa fazer?

Seu handler deve aceitar uma entrega quando qualquer assinatura fornecida corresponder a um segredo em que ele confia.

Um receptor que verifica apenas a primeira assinatura pode rejeitar entregas válidas depois de trocar de segredo.

A especificação Standard Webhooks define uma lista de assinaturas para que os receptores possam testar cada uma durante a rotação. Teste seu verificador com múltiplas assinaturas antes de rotacionar um endpoint em produção.

Mantenha as verificações de timestamp e de duplicação durante toda a mudança. Verificação de assinatura cobre essas verificações.

Qual é a sequência segura?

Salve e implante o novo segredo. Confirme a verificação antes que a sobreposição do segredo antigo termine.

1. Rotacione o segredo do endpoint e armazene o valor retornado imediatamente.
2. Implante o novo valor em todas as instâncias do receptor dentro da sobreposição de 24 horas.
3. Confirme que os receptores verificam entregas usando o novo segredo, por meio dos logs do receptor e das tentativas de entrega de Bird.
4. Deixe o segredo anterior expirar automaticamente após a sobreposição.

Não há uma etapa separada de remoção na operação de rotação. Se o segredo antigo foi exposto, pare de confiar nele nos seus receptores depois que eles tiverem o novo. Rotacionar sozinho deixa os receptores que confiam no segredo antigo expostos durante a sobreposição.

E se eu rotacionar novamente logo em seguida?

Outra rotação pode ser bem-sucedida até que o endpoint atinja cinco segredos válidos simultaneamente.

Começando com um segredo, quatro rotações podem preencher esses cinco slots antes que segredos mais antigos expirem. A próxima rotação falha com WebhookTooManySecrets. Um loop de rotação pode, portanto, impedir que outro segredo seja emitido quando você precisar.

Aguarde um segredo mais antigo expirar antes de rotacionar novamente. Rotações repetidas não eliminam a necessidade de implantar o novo segredo nos seus receptores.

O que acontece com entregas que falharam durante a mudança?

Bird tenta novamente entregas que falharam, então corrigir a verificação pode recuperá-las durante a janela de retentativas.

O cronograma abrange aproximadamente 27,5 horas antes de ajustes de tempo. Uma entrega que falhou também pode ser recuperada por replay após o término das retentativas; retentativas de webhook com falha explica a janela de replay.

Retorne um erro para uma solicitação que você não consegue verificar. Retornar 2xx marca a entrega como bem-sucedida, o que a exclui do replay de eventos perdidos.