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.
- Servir o endpoint via HTTPS e responder rapidamente
- Permitir apenas os IPs de origem do Pluggy
- Exigir um cabeçalho de autenticação
- Verificar a assinatura
- 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
5xxquando 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.
{
"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…
| Parte | Significado |
|---|---|
t | Timestamp Unix, em segundos, desta tentativa de entrega. Cada nova tentativa é assinada novamente com um novo t. |
v1 | HMAC-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#
- 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á.
- Analise
tev1deX-Pluggy-Signature. Rejeite a solicitação se o cabeçalho estiver ausente ou malformado. - Rejeite a solicitação se
testiver 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. - Calcule HMAC-SHA256 de
<t>.<corpo bruto>com seu secret e compare-o comv1usando uma comparação em tempo constante. - Responda
401se 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.
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:
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:
- Antes de regenerar, faça seu receptor responder a uma falha de assinatura com
503em vez de401. Um401nunca é tentado novamente; um503é, então uma notificação que chega durante a janela retorna mais tarde em vez de ser descartada. - Regenerar o secret e copiar o novo valor.
- 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.
- 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.
- 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 cujoclientIdnã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 eventoitem/*, 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
eventIdcomo a chave: o mesmoeventIdchegando duas vezes é o mesmo evento, então o segundo é um no-op que ainda responde2xx. Tentativas e reenvios manuais repetem um evento; duplicatas são normais. - Ignore o que você não espera. Um tipo de
eventque você não manipula, ou uma carga útil faltando os campos que você precisa, recebe um2xxe 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
2xxdentro de 10 segundos, processando depois. - Solicitações de fora dos IPs do Pluggy são descartadas.
- Webhooks criados com
POST /webhookscarregam um secret emheaders, e solicitações sem ele recebem401. - 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
503em vez de401a 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, eeventIdtorna o processamento idempotente.- Secrets vivem em seu armazenamento de secrets, nunca em controle de versão ou logs.
Resumo#
| Medida | Protege contra | Não protege contra |
|---|---|---|
| Endpoint HTTPS | Leitura ou modificação da solicitação na rede | Qualquer um enviando sua própria solicitação para sua URL |
| Lista de IPs permitidos | Solicitações de hosts arbitrários | Corpos forjados ou alterados; não diz nada sobre integridade |
| Cabeçalho de autenticação | Solicitações de chamadores sem o secret | Reproduçã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 minutos | Um secret de assinatura vazado; reproduções dentro da janela de 5 minutos |
| Validar e buscar novamente | Agir em notificações forjadas, obsoletas, duplicadas ou estrangeiras | Solicitações chegando ao seu endpoint em primeiro lugar |
