Pular para o conteúdo principal

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 com GET 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.

MomentoSecret usado na assinatura
Antes de salvar a trocaAntigo
Até 5 minutos depois de salvarAntigo, em eventos novos
Mais de 5 minutos depois de salvarNovo
Notificações já em nova tentativa, por até 48 horasAntigo

Passo 3 — Atualizar o webhook na NFE.io​

Escolha uma das duas formas. As duas fazem a mesma chamada.

atenção

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​

SintomaCausa provávelO que fazer
O servidor rejeita notificações logo após a trocaO validador aceita só o secret novo, ou o valor foi copiado com espaço ou quebra de linhaAceite os dois secrets e confira o tamanho do valor
Salvei com o campo em brancoA NFE.io gerou um secret que ninguém lêRepita a troca informando um valor seu
A assinatura falha com o secret corretoO corpo foi lido e gravado de novo antes do cálculoCalcule sobre o corpo bruto
O webhook perdeu campos depois do PUTO PUT substitui o registro inteiroEnvie outro PUT com todos os campos
Cada evento chega duas vezesExistem dois webhooks para a mesma URLRemova o webhook extra e use PUT no existente
Notificações da janela de troca não chegaramRespostas 4xx encerram a entrega sem nova tentativaFale com o suporte para avaliar o reenvio das notas do período

Próximos passos​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.