Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

Segurança do Webhook

Como confiar em um webhook do Pluggy: HTTPS, IPs de origem, um cabeçalho de autenticação, a assinatura HMAC e a nova busca dos dados, e o que cada um protege e não protege.

Ver como Markdown

Segurança do Webhook#

Seu endpoint de webhook é uma URL pública. Qualquer pessoa que a encontrar pode enviar uma solicitação que pareça uma notificação do Pluggy, e uma solicitação que realmente veio do Pluggy poderia, em princípio, ser lida ou alterada em seu caminho até você. Nenhuma verificação única cobre tudo isso, então combine as camadas abaixo. Cada seção diz contra o que a camada protege e o que ela deixa em aberto.

  1. Servir o endpoint via HTTPS e responder rapidamente
  2. Permitir apenas os IPs de origem do Pluggy
  3. Exigir um cabeçalho de autenticação
  4. Verificar a assinatura
  5. Validar a carga útil e buscar os dados novamente

A lista de verificação e a tabela resumo no final as colocam lado a lado.

1. HTTPS e rápido 2xx#

O Pluggy só entrega para URLs públicas HTTPS (veja os requisitos de URL), então a solicitação e seu corpo são criptografados em trânsito.

Responda com um 2xx assim que você aceitar a solicitação, e faça o processamento depois. Um manipulador que leva mais de 10 segundos é contado como uma falha e será tentado novamente, e alguns status de erro nunca são tentados novamente. As regras estão em Tratamento de notificações; a versão curta para segurança é:

  • Rejeite uma solicitação que falhe em uma das verificações abaixo com 401. Ela não será tentada novamente, o que é o que você deseja para uma solicitação que não é do Pluggy.
  • Retorne 5xx quando o problema estiver do seu lado e for temporário, para que a notificação retorne.

Protege contra: leitura ou modificação da solicitação na rede.
Não protege contra: qualquer pessoa na internet enviando sua própria solicitação para sua URL. HTTPS prova quem você é, não quem é o chamador.

2. Permitir apenas os IPs de origem do Pluggy#

Os webhooks saem do Pluggy de um conjunto publicado de endereços. Permita-os em seu firewall, balanceador de carga ou manipulador e descarte tudo o mais. A lista vive em um só lugar, então está sempre atualizada: a nota "Lista de IPs do Pluggy" em Respondendo a notificações.

Protege contra: solicitações de hosts arbitrários na internet.
Não protege contra: uma solicitação que passe por um caminho de rede permitido, mas carregue um corpo forjado ou alterado. Um endereço IP diz de qual rede uma solicitação veio, não quem a escreveu ou se o corpo é o que o Pluggy enviou. Mantenha-o como um filtro grosseiro na frente das verificações abaixo, nunca como o único.

3. Exigir um cabeçalho de autenticação#

Quando você cria um webhook com POST /webhooks, você pode fornecer um objeto headers. Coloque um secret longo e aleatório lá, por exemplo em Authorization, e faça seu endpoint responder 401 a qualquer solicitação que não o carregue. Veja Cabeçalhos do Webhook.

json
{
  "url": "https://hooks.example.com/pluggy",
  "event": "all",
  "headers": {
    "Authorization": "Bearer <um valor longo e aleatório>"
  }
}

Um webhookUrl definido em um Item ou um Connect Token não envia cabeçalhos personalizados, então não exija um nessa URL. A assinatura cobre essas entregas também.

Protege contra: solicitações de qualquer um que não conheça o secret.
Não protege contra: um valor vazado. O cabeçalho é o mesmo em cada solicitação, então qualquer um que veja uma entrega — em um log de proxy, um relatório de erro, uma ferramenta de depuração — pode reproduzi-lo ou anexá-lo a um corpo próprio. Ele também não diz nada sobre se o corpo foi alterado.

4. Verificar a assinatura#

A assinatura é a única camada que prova que uma notificação foi enviada pelo Pluggy e que seu corpo não foi alterado. É opcional e configurada por aplicativo.

Ative-a#

No Dashboard, abra seu aplicativo e, em Webhooks, escolha Gerar secret de assinatura. Apenas o Proprietário da equipe pode gerar, regenerar ou removê-lo.

O secret é whsec_ seguido por 64 caracteres hexadecimais. Ele é mostrado uma vez: armazene-o como um secret na configuração do receptor do seu webhook antes de fechar o diálogo.

A partir de então, cada entrega de webhook para esse aplicativo carrega um cabeçalho de assinatura — seja para um webhook criado com POST /webhooks ou para um webhookUrl definido em um Item ou um Connect Token:

X-Pluggy-Signature: t=1795000000,v1=5f2b…
ParteSignificado
tTimestamp Unix, em segundos, desta tentativa de entrega. Cada nova tentativa é assinada novamente com um novo t.
v1HMAC-SHA256 em minúsculas do string <t>.<corpo da solicitação bruta>, usando o secret completo (incluindo o prefixo whsec_) como chave, codificado como UTF-8.

X-Pluggy-Signature é definido pelo Pluggy. Um cabeçalho com esse nome nos headers do seu webhook não o define ou substitui.

Verifique cada solicitação#

  1. Leia o corpo bruto exatamente como chegou, antes de qualquer análise JSON. Analisar e re-serializar altera os bytes, e a assinatura não corresponderá.
  2. Analise t e v1 de X-Pluggy-Signature. Rejeite a solicitação se o cabeçalho estiver ausente ou malformado.
  3. Rejeite a solicitação se t estiver mais de 5 minutos distante do seu relógio. Uma assinatura antiga ainda é uma assinatura válida, então essa tolerância é o que impede que uma solicitação capturada seja reproduzida mais tarde.
  4. Calcule HMAC-SHA256 de <t>.<corpo bruto> com seu secret e compare-o com v1 usando uma comparação em tempo constante.
  5. Responda 401 se nada corresponder. Só então analise o JSON.

Os auxiliares abaixo aceitam uma lista de secrets, então o mesmo código aceita o secret antigo e o novo durante uma rotação.

js
import { createHmac, timingSafeEqual } from "node:crypto";
 
const TOLERANCE_SECONDS = 5 * 60;
 
// rawBody: o corpo da solicitação como um Buffer, antes de qualquer análise JSON.
// header:  o valor de X-Pluggy-Signature.
// secrets: os secrets de assinatura que você atualmente aceita, por exemplo [atual, anterior].
export function verifyPluggySignature(rawBody, header, secrets) {
  const parts = new Map(
    String(header ?? "")
      .split(",")
      .map((part) => {
        const i = part.indexOf("=");
        return [part.slice(0, i).trim(), part.slice(i + 1).trim()];
      }),
  );
 
  const t = parts.get("t");
  const received = parts.get("v1");
  // O cabeçalho é uma entrada não confiável: rejeite qualquer coisa que não seja um timestamp decimal simples
  // e um digest hex de 64 caracteres.
  if (!t || !received || !/^[0-9]{1,12}$/.test(t) || !/^[0-9a-f]{64}$/.test(received)) return false;
 
  // Anti-replay: rejeite uma assinatura com mais de 5 minutos.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > TOLERANCE_SECONDS) return false;
 
  const receivedBytes = Buffer.from(received, "utf8");
  return secrets.some((secret) => {
    const expected = createHmac("sha256", secret)
      .update(`${t}.`)
      .update(rawBody)
      .digest("hex");
    const expectedBytes = Buffer.from(expected, "utf8");
    return (
      expectedBytes.length === receivedBytes.length &&
      timingSafeEqual(expectedBytes, receivedBytes)
    );
  });
}

Integrado em um aplicativo Express, mantendo o corpo bruto:

js
import express from "express";
 
const app = express();
 
const SECRETS = [process.env.PLUGGY_WEBHOOK_SECRET, process.env.PLUGGY_WEBHOOK_SECRET_PREVIOUS].filter(Boolean);
 
app.post("/pluggy/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyPluggySignature(req.body, req.get("X-Pluggy-Signature"), SECRETS)) {
    return res.status(401).end();
  }
 
  const event = JSON.parse(req.body.toString("utf8"));
  enqueue(event); // desduplicar em event.eventId, depois processar
  res.status(200).end();
});

Para verificar sua implementação contra uma entrega que você capturou: HMAC-SHA256 de t + "." + rawBody com seu secret, em hex minúsculo, deve ser igual a v1 caractere por caractere.

Rotacionando o secret#

Regenerar no Dashboard emite um novo secret e substitui o antigo imediatamente: o Pluggy não assina com ambos, e seu receptor não pode saber o novo valor antes que ele exista. Notificações enviadas entre o momento em que você regenera e o momento em que seu receptor tem o novo secret falharão na verificação. Planeje para essa janela em vez de perdê-las:

  1. Antes de regenerar, faça seu receptor responder a uma falha de assinatura com 503 em vez de 401. Um 401 nunca é tentado novamente; um 503 é, então uma notificação que chega durante a janela retorna mais tarde em vez de ser descartada.
  2. Regenerar o secret e copiar o novo valor.
  3. Implante-o em seu receptor ao lado do antigo, para que ele aceite qualquer um (os auxiliares acima aceitam uma lista). Notificações rejeitadas na janela são tentadas novamente e agora verificam.
  4. Continue aceitando o secret antigo por um tempo. Entregas que já estavam na fila para uma nova tentativa antes de você regenerar ainda estão assinadas com ele, por algumas horas.
  5. Remova o secret antigo do seu receptor e volte a responder 401.

As tentativas seguem o cronograma normal, então uma notificação da janela chega tarde. Se você pular a etapa 1, ou a janela durar mais do que as tentativas, as notificações rejeitadas nela não são entregues novamente por conta própria: reenvie-as do Dashboard ou busque novamente os recursos afetados da API.

Um reenvio manual do Dashboard é assinado com o secret que o evento tinha quando foi enviado pela primeira vez. Reenviar um evento de antes de uma rotação, portanto, produz uma assinatura que apenas o secret anterior verifica.

Remover no Dashboard faz com que os webhooks sejam enviados novamente sem assinatura. Se seu receptor exigir a assinatura, ele os rejeitará — pare de exigir isso primeiro.

Uma notificação rejeitada não é tentada novamente

Fora de uma rotação, responda 401 quando uma assinatura não verificar: um 401 não é tentado novamente, o que é o que você deseja para uma solicitação que não é do Pluggy. A mesma regra significa que uma notificação real rejeitada porque seu receptor ainda não tinha o secret correto não é entregue novamente por conta própria. Siga os passos acima quando você rotacionar.

Protege contra: solicitações forjadas e corpos alterados em trânsito ou por um intermediário, de qualquer um que não tenha o secret; reproduções mais antigas que 5 minutos.
Não protege contra: um secret de assinatura vazado — regenere-o se isso acontecer. Uma reprodução dentro da janela de 5 minutos — desduplicar em eventId (próxima seção). E não torna a carga útil uma fonte de verdade: a notificação ainda é apenas uma dica.

5. Validar a carga útil e buscar os dados novamente#

Mesmo uma notificação verificada apenas diz a você que algo aconteceu. Trate-a como uma dica e deixe a API dizer o que é verdade:

  • Verifique clientId. É o aplicativo ao qual o webhook pertence. Ignore qualquer notificação cujo clientId não seja um dos seus.
  • Busque novamente antes de agir. Leia o recurso com sua própria chave de API — por exemplo GET /items/{id} para um evento item/*, conforme descrito em Respondendo a notificações — e aja com base no que a API retorna, não na carga útil.
  • Torne o manipulador idempotente. Use eventId como a chave: o mesmo eventId chegando duas vezes é o mesmo evento, então o segundo é um no-op que ainda responde 2xx. Tentativas e reenvios manuais repetem um evento; duplicatas são normais.
  • Ignore o que você não espera. Um tipo de event que você não manipula, ou uma carga útil faltando os campos que você precisa, recebe um 2xx e nenhuma ação.

Protege contra: agir em uma notificação forjada, obsoleta, duplicada ou fora de ordem, e agir com base nos dados de outra conta.
Não protege contra: solicitações forjadas chegando ao seu endpoint — é para isso que servem as camadas 2 a 4. Buscar novamente limita o dano de uma notificação forjada a uma chamada extra à API.

Lista de verificação#

  • O endpoint é HTTPS e responde 2xx dentro de 10 segundos, processando depois.
  • Solicitações de fora dos IPs do Pluggy são descartadas.
  • Webhooks criados com POST /webhooks carregam um secret em headers, e solicitações sem ele recebem 401.
  • O aplicativo tem um secret de assinatura, e cada solicitação é verificada sobre o corpo bruto, com uma comparação em tempo constante e uma tolerância de 5 minutos em t.
  • O receptor aceita uma lista de secrets de assinatura, e durante uma rotação responde 503 em vez de 401 a uma falha de assinatura: o novo secret não pode ser implantado antes de existir, e apenas uma notificação tentada novamente sobrevive a essa janela.
  • clientId é verificado, o recurso é buscado novamente com sua própria chave de API, e eventId torna o processamento idempotente.
  • Secrets vivem em seu armazenamento de secrets, nunca em controle de versão ou logs.

Resumo#

MedidaProtege contraNão protege contra
Endpoint HTTPSLeitura ou modificação da solicitação na redeQualquer um enviando sua própria solicitação para sua URL
Lista de IPs permitidosSolicitações de hosts arbitráriosCorpos forjados ou alterados; não diz nada sobre integridade
Cabeçalho de autenticaçãoSolicitações de chamadores sem o secretReprodução ou reutilização de um cabeçalho vazado; corpos alterados. Não enviado para um webhookUrl em um Item ou Connect Token
Assinatura (HMAC)Solicitações forjadas e corpos alterados; reproduções mais antigas que 5 minutosUm secret de assinatura vazado; reproduções dentro da janela de 5 minutos
Validar e buscar novamenteAgir em notificações forjadas, obsoletas, duplicadas ou estrangeirasSolicitações chegando ao seu endpoint em primeiro lugar
Esta página foi útil?