# 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 a carga útil e buscar os dados novamente](#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

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](/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), 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](/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 nessa 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-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

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](#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 **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](/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 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](/docs/developer-tools/webhooks-ref#retry-schedule) 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.

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

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