---
title: "Trocar o secret de um webhook"
description: "Troque o secret de um webhook sem perder notificações. Aceite os dois secrets por 48 horas, atualize o webhook e confirme as entregas."
source_url: https://nfe.io/docs/documentacao/webhooks/trocar-secret-do-webhook/
product: documentacao
last_updated: 2026-11-17
tags: ["tutorial", "webhook", "seguranca"]
---

# 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.

```bash
openssl rand -hex 24
```

```powershell
[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>`.

```typescript

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.

:::warning
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.

```bash
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 |

## Próximos passos

- [Cadastrar, consultar, editar e excluir webhooks](/documentacao/webhooks/integracao/)
- [Conceitos de webhook na NFE.io](/documentacao/webhooks/conceitos/)
- [Dúvidas frequentes sobre webhook](/documentacao/webhooks/duvidas-frequentes/)
