Trocar o secret de um webhook
Este tutorial mostra como trocar o secret de um webhook da NFE.io sem perder notificações. O secret é a senha que a NFE.io usa para assinar cada notificação enviada ao seu servidor. Reserve cerca de 30 minutos de trabalho e mais 48 horas até remover o secret antigo.
A NFE.io guarda um único secret por webhook. A plataforma nunca assina com os dois ao mesmo tempo. Por isso, o seu servidor precisa aceitar o secret antigo e o novo durante a troca.
Pré-requisitos
- Acesso à tela de webhooks da conta, ou a chave de API da conta.
- O identificador (
id) do webhook. Consulte pela tela ou comGET https://api.nfse.io/v2/webhooks. - Acesso ao código do servidor que recebe as notificações e valida a assinatura.
- Um cofre de segredos para guardar o novo valor.
Passo 1 — Gerar o novo secret
Gere um valor aleatório de 32 a 64 caracteres. Os comandos abaixo produzem 48 caracteres.
openssl rand -hex 24
[Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(24))
Guarde o valor no cofre de segredos agora. Depois de salvo, nenhuma consulta da NFE.io mostra o secret.
Não deixe o campo em branco ao salvar. Com o campo em branco, a NFE.io gera um secret aleatório que ninguém consegue ler. O seu servidor deixa de validar as notificações.
Passo 2 — Aceitar os dois secrets no seu servidor
Atualize o validador para aceitar o secret novo e o antigo. Faça isso antes de alterar o webhook.
A NFE.io assina o corpo bruto da notificação com HMAC-SHA1, um cálculo de hash com chave. O resultado vai no cabeçalho X-Hub-Signature, no formato sha1=<valor em hexadecimal>.
import { createHmac, timingSafeEqual } from "node:crypto";
function assinaturaValida(
corpoBruto: Buffer,
cabecalho: string,
segredos: string[], // [secret novo, secret antigo]
): boolean {
const recebida = Buffer.from(cabecalho.replace(/^sha1=/i, "").toLowerCase());
return segredos.some((segredo) => {
const calculada = Buffer.from(
createHmac("sha1", segredo).update(corpoBruto).digest("hex"),
);
return calculada.length === recebida.length && timingSafeEqual(calculada, recebida);
});
}
Calcule a assinatura sobre o corpo exatamente como chegou. Se você ler o JSON e gravá-lo de novo, a assinatura deixa de bater.
Os dois secrets são necessários por um motivo prático. Veja qual secret assina cada notificação.
| Momento | Secret usado na assinatura |
|---|---|
| Antes de salvar a troca | Antigo |
| Até 5 minutos depois de salvar | Antigo, em eventos novos |
| Mais de 5 minutos depois de salvar | Novo |
| Notificações já em nova tentativa, por até 48 horas | Antigo |
Passo 3 — Atualizar o webhook na NFE.io
Escolha uma das duas formas. As duas fazem a mesma chamada.
Não crie um segundo webhook para a mesma URL. A NFE.io entrega cada evento uma vez por webhook. O seu servidor receberia tudo em duplicata.
Pela tela. No portal da conta (account.nfe.io), abra a assinatura e acesse Webhooks. Abra o webhook e preencha o campo "Senha para autenticação da mensagem (HMAC)" com o novo secret. O campo aparece vazio mesmo quando já existe um secret salvo. Não altere os outros campos e clique em Salvar.
Pela API. Envie um PUT ao webhook existente. O PUT substitui o registro inteiro. Reenvie todos os campos, não só o secret.
curl --request PUT "https://api.nfse.io/v2/webhooks/{webhookId}" \
--header "Authorization: SUA_CHAVE_DE_API" \
--header "Content-Type: application/json" \
--data '{
"webHook": {
"uri": "https://exemplo.com/webhooks/nfeio",
"contentType": "json",
"insecureSsl": false,
"status": "Active",
"filters": [
"service_invoice.issued_successfully",
"service_invoice.issued_error"
],
"secret": "NOVO_SECRET"
}
}'
Antes do PUT, consulte o webhook com GET https://api.nfse.io/v2/webhooks/{webhookId} e copie uri, contentType, insecureSsl, status e filters. A consulta pode não mostrar todos os campos do registro, como cabeçalhos personalizados. Se o seu webhook usa campos que a consulta não mostra, confirme com o suporte antes de salvar.
Passo 4 — Aguardar a propagação e validar
A alteração vale para eventos novos em até 5 minutos. Aguarde esse tempo antes de concluir que algo falhou.
Valide com notificações reais. Aguarde a próxima notificação da conta, ou emita uma nota que gere um evento selecionado no webhook. Confira nos registros do seu servidor se a assinatura foi aceita.
Não use o endpoint de ping como teste. Ele responde 204 e não gera uma notificação.
Saiba como a NFE.io trata a resposta do seu servidor. Respostas 2xx encerram a entrega com sucesso. As respostas 400, 401, 403, 404, 405, 410 e 422 encerram sem nova tentativa. Respostas 5xx e falhas de conexão geram até 16 tentativas, em até cerca de 48 horas.
Passo 5 — Remover o secret antigo
Mantenha os dois secrets por 48 horas depois de salvar a troca. Depois desse prazo, nenhuma notificação em nova tentativa carrega o secret antigo. Remova o secret antigo do código e do cofre de segredos.
Se você suspeita que o secret antigo vazou, troque sem janela de transição. Aceite falhas temporárias de validação. Elas custam menos do que manter um secret exposto.
Verificar o resultado
Confirme os três pontos abaixo.
- O seu servidor aceita notificações assinadas com o secret novo.
- Os registros do servidor não mostram rejeições de assinatura depois das primeiras horas.
- Depois de 48 horas, o servidor valida só com o secret novo e continua aceitando as notificações.
Resolver problemas comuns
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| O servidor rejeita notificações logo após a troca | O validador aceita só o secret novo, ou o valor foi copiado com espaço ou quebra de linha | Aceite os dois secrets e confira o tamanho do valor |
| Salvei com o campo em branco | A NFE.io gerou um secret que ninguém lê | Repita a troca informando um valor seu |
| A assinatura falha com o secret correto | O corpo foi lido e gravado de novo antes do cálculo | Calcule sobre o corpo bruto |
O webhook perdeu campos depois do PUT | O PUT substitui o registro inteiro | Envie outro PUT com todos os campos |
| Cada evento chega duas vezes | Existem dois webhooks para a mesma URL | Remova o webhook extra e use PUT no existente |
| Notificações da janela de troca não chegaram | Respostas 4xx encerram a entrega sem nova tentativa | Fale com o suporte para avaliar o reenvio das notas do período |