# Segurança do Webhook

## 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](#1-https-and-fast-2xx)
2. [Permitir apenas os IPs de origem do Pluggy](#2-allow-only-pluggys-source-ips)
3. [Exigir um cabeçalho de autenticação](#3-require-an-authentication-header)
4. [Verificar a assinatura](#4-verify-the-signature)
5. [Validar o payload e reobter os dados](#5-validate-the-payload-and-re-fetch-the-data)

A [lista de verificação](#checklist) e a [tabela resumo](#summary) 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](/docs/reference/webhooks#url-requirements)), 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](/docs/developer-tools/webhooks-ref#handling-notifications); 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

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](/docs/developer-tools/webhooks-ref#responding-to-notifications).

**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`](/docs/reference/webhooks#webhook-resource) ou o atualiza com `PATCH /webhooks/{id}`, você pode fornecer um objeto `headers`. O Proprietário da aplicação também pode configurá-los no Dashboard, sob **Webhooks**, onde os valores nunca são mostrados novamente após a gravação. 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](/docs/developer-tools/webhooks-ref#webhook-headers).

```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 nesse URL. A [assinatura](#4-verify-the-signature) 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-la ou anexá-la a um corpo próprio. 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 aplicação: uma aplicação sem um secret de assinatura continua recebendo suas notificações não assinadas, exatamente como antes.

### Ative-a

No Dashboard, abra sua aplicação 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.

Uma vez que uma aplicação tenha um secret, uma notificação nunca é enviada sem a assinatura. Se o Pluggy não puder assinar uma, ela é retida e [tentada novamente](/docs/developer-tools/webhooks-ref#retry-schedule) em vez de ser enviada sem assinatura. Um novo secret leva alguns segundos para se tornar ativo, então uma notificação levantada logo após você gerar seu **primeiro** secret pode chegar cerca de 15 minutos atrasada, assinada.

A partir de então, cada entrega de webhook para essa aplicação carrega um cabeçalho de assinatura — seja ela enviada 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

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 do que **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](#rotating-the-secret).

<CodeGroup>
<CodeTab title="Node.js">

```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();
});
```

</CodeTab>
<CodeTab title="Python">

```python
import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 5 * 60
TIMESTAMP = re.compile(r"[0-9]{1,12}\Z")
DIGEST = re.compile(r"[0-9a-f]{64}\Z")


def verify_pluggy_signature(raw_body, header, secrets):
    """raw_body: o corpo da solicitação como bytes, 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]."""
    parts = {}
    for part in (header or "").split(","):
        key, sep, value = part.partition("=")
        if sep:
            parts[key.strip()] = value.strip()

    t = parts.get("t")
    received = parts.get("v1")
    # O cabeçalho é uma entrada não confiável: qualquer coisa que não seja um timestamp decimal simples
    # e um digest hex de 64 caracteres é rejeitada, nunca analisada.
    if not t or not received or not TIMESTAMP.match(t) or not DIGEST.match(received):
        return False

    # Anti-replay: rejeite uma assinatura com mais de 5 minutos.
    if abs(int(time.time()) - int(t)) > TOLERANCE_SECONDS:
        return False

    signed = t.encode("utf-8") + b"." + raw_body
    for secret in secrets:
        expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
        if hmac.compare_digest(expected, received):
            return True
    return False
```

Integrado em um aplicativo Flask, mantendo o corpo bruto:

```python
import json
import os

from flask import Flask, request

app = Flask(__name__)

SECRETS = [s for s in (os.environ.get("PLUGGY_WEBHOOK_SECRET"), os.environ.get("PLUGGY_WEBHOOK_SECRET_PREVIOUS")) if s]


@app.post("/pluggy/webhooks")
def pluggy_webhook():
    raw = request.get_data()  # os bytes que o Pluggy assinou
    if not verify_pluggy_signature(raw, request.headers.get("X-Pluggy-Signature"), SECRETS):
        return "", 401

    event = json.loads(raw)
    enqueue(event)  # desduplicar em event["eventId"], depois processar
    return "", 200
```

</CodeTab>
</CodeGroup>

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 **dentro de segundos** (até então, as notificações ainda são assinadas com o antigo): 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](/docs/developer-tools/webhooks-ref#responses-we-do-not-retry); 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 alguns minutos. A mudança chega a cada entrega em cerca de um minuto, e uma solicitação já a caminho de você ainda é assinada com o antigo.
5. Remova o secret antigo do seu receptor e volte a responder `401`.

As tentativas seguem o [cronograma normal](/docs/developer-tools/webhooks-ref#retry-schedule), então uma notificação da janela chega atrasada. 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 reobtenha os recursos afetados da API.

Tentativas e reenvios manuais do Dashboard são assinados com o secret **atual** da aplicação no momento em que são enviados, qualquer que seja o secret que a primeira tentativa usou. Um evento reenviado após uma rotação verifica com o novo secret, e um reenviado após a remoção do secret chega sem assinatura.

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

<Callout variant="warning" title="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.
</Callout>

**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 o payload uma fonte de verdade: a notificação ainda é apenas uma dica.

## 5. Validar o payload e reobter os dados

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`.** É a aplicação à qual o webhook pertence. Ignore qualquer notificação cujo `clientId` não seja um dos seus.
- **Reobtenha 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](/docs/developer-tools/webhooks-ref#responding-to-notifications) — e aja com base no que a API retorna, não no payload.
- **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 um payload 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. Reobter 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](/docs/developer-tools/webhooks-ref#responding-to-notifications) são descartadas.
- Webhooks criados com `POST /webhooks` carregam um secret em `headers`, e solicitações sem ele recebem `401`.
- A aplicação 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](#rotating-the-secret) 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 é reobtenido 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

| 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 reobter | Agir em notificações forjadas, obsoletas, duplicadas ou estrangeiras | Solicitações chegando ao seu endpoint em primeiro lugar |