# Webhook

## Webhook

Neste guia, abordaremos os webhooks que são enviados pelo Pluggy para criar uma integração reativa a mudanças. Isso abrangerá tanto integrações de dados quanto de pagamentos.

Um Webhook é uma ferramenta que permite que você receba uma notificação para um determinado evento. Ele permite que você configure uma URL HTTPS em nossa plataforma para certos eventos, e você receberá um evento JSON POST nessa URL, com dados específicos do evento.

Para se inscrever em eventos de Webhook, você pode:

- Criar uma instância de Webhook diretamente, ou
- Especificar o parâmetro `webhookUrl` (com uma URL HTTPS válida), ao:
  - criar um Item,
  - criar um Connect Token, ou
  - criar uma Solicitação de Pagamento

Se você criar uma instância de Webhook diretamente, estará se inscrevendo para todos os casos de eventos do tipo de evento especificado. Em vez disso, se você fizer isso especificando o `webhookUrl` ao criar um Item ou criar um Connect Token, você será notificado sobre todos os eventos, mas apenas relacionados a esse recurso específico. Ou seja, seja para aquele Item especificamente, ou para o(s) item(ns) relacionados criados usando aquele Connect Token.

## Eventos de Dados

Apoiamos o registro para os seguintes eventos ao consumir os endpoints de dados do Pluggy.

| Evento | Descrição |
|-------|-------------|
| `item/created` | Um item foi criado e terminou de se conectar com sucesso. |
| `item/updated` | Um item foi atualizado e sincronizado com sucesso. |
| `item/deleted` | Um item foi excluído com sucesso. |
| `item/error` | Um item encontrou erros em sua execução. O caso de `USER_AUTHORIZATION_PENDING` também acionará este evento. |
| `item/waiting_user_input` | Um item está bloqueado aguardando a entrada do usuário para continuar. |
| `item/waiting_user_action` | Um item está bloqueado aguardando que o usuário aprove uma ação em seu dispositivo (por exemplo, autorizar acesso no aplicativo bancário ou escanear um código QR). |
| `item/login_succeeded` | Um item fez login com sucesso no provedor e está coletando os dados. |
| `connector/status_updated` | Um conector mudou de status (`ONLINE`/`UNSTABLE`/`OFFLINE`). Este evento informa o ID do conector afetado e o status atualizado. Verifique o endpoint de Conectores para ver todos os conectores e seus IDs. |
| `transactions/deleted` | IDs de transações excluídas após mesclar dados na atualização do item. |
| `transactions/created` | Receba este evento de webhook e use a página `createdTransactionsLink` para acessar todas as transações disponíveis e inseri-las em sua fonte de dados. |
| `transactions/updated` | IDs de transações atualizadas após mesclar dados na atualização do item. Após receber este webhook, é recomendável obter os dados completos das transações usando o endpoint de transações com o parâmetro `ids`. |

<Callout variant="info">
Os webhooks de transações são acionados apenas quando há uma mudança de dados. Se não houver transações, não será acionado um evento `transactions/created`.
</Callout>

## Eventos de Pagamento

Apoiamos o registro para os seguintes eventos ao consumir os endpoints de pagamento do Pluggy.

### Intenção de Pagamento

| Evento | Descrição |
|-------|-------------|
| `payment_intent/created` | ID da intenção de pagamento criada pelo usuário, com `paymentRequestId`. |
| `payment_intent/completed` | ID da intenção de pagamento concluída com sucesso pelo usuário, com `paymentRequestId`. |
| `payment_intent/waiting_payer_authorization` | ID da intenção de pagamento quando precisa de autorização adicional. |
| `payment_intent/error` | ID da intenção de pagamento quando ocorre um erro durante o fluxo, com `paymentRequestId`. |
| `payment_request/updated` | O status da solicitação de pagamento foi alterado. |

### Pagamento Programado

| Evento | Descrição |
|-------|-------------|
| `scheduled_payment/created` | IDs da autorização de pagamento programado. |
| `scheduled_payment/completed` | Um único pagamento da autorização foi realizado. |
| `scheduled_payment/error` | Pagamento não concluído, finalizado com erro. |
| `scheduled_payment/canceled` | Pagamento cancelado pelo usuário ou pelo cliente. |

### Pagamento Automático PIX

| Evento | Descrição |
|-------|-------------|
| `automatic_pix_payment/created` | Um pagamento foi programado para uma solicitação de pagamento automático PIX. |
| `automatic_pix_payment/completed` | Um pagamento programado associado a uma solicitação de pagamento automático PIX foi concluído com sucesso. |
| `automatic_pix_payment/error` | Um pagamento programado associado a uma solicitação de pagamento automático PIX terminou com erro. |
| `automatic_pix_payment/canceled` | Um pagamento programado associado a uma solicitação de pagamento automático PIX foi cancelado. |

### Transferência Inteligente

| Evento | Descrição |
|-------|-------------|
| `smart_transfer_preauthorization/completed` | Uma pré-autorização de transferência inteligente foi aprovada por um usuário. |
| `smart_transfer_preauthorization/error` | Ocorreu um erro durante a aprovação da pré-autorização de transferência inteligente. Por exemplo, quando o usuário rejeita o consentimento. |
| `smart_transfer_payment/completed` | Um pagamento de transferência inteligente foi concluído. |
| `smart_transfer_payment/error` | Ocorreu um erro ao liquidar o pagamento de transferência inteligente. Por exemplo, quando a conta não tem saldo suficiente. |

### PIX por biometria

Os pagamentos PIX por biometria enviam os eventos de [Intenção de Pagamento](#payment-intent). Estes relatam as contas vinculadas do pagador (veja [Gerenciando contas vinculadas](/docs/payments/pix-biometric-enrollments)).

| Evento | Descrição |
|-------|-------------|
| `pix_biometric_enrollment/authorized` | O pagador concluiu a vinculação de uma conta. |
| `pix_biometric_enrollment/revoked` | Uma conta vinculada foi revogada, no banco ou através da API. |
| `pix_biometric_enrollment/error` | O vínculo não foi concluído: foi rejeitado ou terminou antes que o pagador o finalizasse. |

Para se registrar em um evento específico, você terá que enviar o evento desejado para ouvir apenas aqueles eventos de webhook.

Alternativamente, você pode apenas usar a opção `all` para receber todos os eventos associados.

Aceitamos apenas URLs HTTPS. URLs localhost não são permitidas; você terá que fornecer uma URL HTTPS usando ngrok ou outras ferramentas para fornecer URLs públicas e seguras.

<Callout variant="info" title="Dica">
Para testar essa funcionalidade, você pode usar [RequestCatcher](https://requestcatcher.com), que é uma ferramenta que apenas receberá nossa notificação e mostrará o payload. Você pode facilmente criar um catcher com apenas um nome em segundos.
</Callout>

## Parâmetros do Payload

Ao fazer a solicitação POST, todos os webhooks enviarão os seguintes parâmetros em formato JSON:

- **event:** nome do evento (`item/created`, `item/updated`, `item/error`, etc.)
- **eventId:** identificador do evento em si. Deve ser o mesmo para um evento quando é enviado para muitos endpoints.
- **clientId:** o ID do Cliente da aplicação à qual o webhook pertence. Use-o para [verificar se uma notificação é para você](#verifying-notifications).
- **triggeredBy:** quem acionou o evento (para todos os eventos, exceto `item/deleted`, `connector/status_updated` e `transactions/deleted`). Valores possíveis:
  - `USER`: um usuário final acionou o evento com um Connect Token (por exemplo, do Pluggy Connect)
  - `CLIENT`: um cliente acionou o evento com uma Chave de API (por exemplo, executando PATCH em um Item)
  - `SYNC`: Auto-sync acionou o evento
  - `INTERNAL`: Foi acionado por alguém da equipe de suporte do Pluggy

Dependendo do tipo de evento, o ID da entidade é enviado. Por exemplo, para itens, `itemId`. Em transações, `transactionIds`, e em conectores, `connectorId`.

### `clientUserId` é enviado apenas em eventos `item/*`

`clientUserId` -- o identificador que você definiu ao [criar o Connect Token](/docs/authentication) -- está incluído no payload de **cada evento `item/*`**: `item/created`, `item/updated`, `item/error`, `item/deleted`, `item/login_succeeded`, `item/waiting_user_input` e `item/waiting_user_action`.

Não está **não** incluído em eventos `transactions/*`. Esses payloads carregam `itemId`, `accountId` e os campos da transação, mas não `clientUserId`. Para atribuir um evento de transação a um usuário final, mantenha seu próprio mapeamento `itemId` -> usuário (que você já possui do evento `item/created` ou do callback `onSuccess` do widget) e resolva a partir de `itemId`.

<Callout variant="info" title="Se `clientUserId` chegar como `null` em eventos `item/*`">
A causa usual é que foi enviado na **raiz** do corpo `POST /connect_token` em vez de dentro de `options`. A API descarta propriedades desconhecidas da raiz e ainda retorna `200`, então o valor nunca chega ao Item. Veja [Configurando um Connect Token](/docs/authentication). Você pode preencher os Itens afetados com [PATCH /items/{id}](/reference/items-update).
</Callout>

### Exemplos de Item

**item/created:**

```json
{
  "event": "item/created",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}
```

**item/updated:**

```json
{
  "event": "item/updated",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}
```

**item/deleted:**

```json
{
  "event": "item/deleted",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}
```

**item/error:**

```json
{
  "event": "item/error",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "d161a74a-8bc8-4093-88de-724312969b0d",
  "error": {
    "code": "USER_INPUT_TIMEOUT",
    "message": "A entrada solicitada pelo usuário expirou",
    "parameter": "token"
  },
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}
```

**item/waiting_user_input:**

```json
{
  "event": "item/waiting_user_input",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}
```

**item/waiting_user_action:**

```json
{
  "event": "item/waiting_user_action",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}
```

**item/login_succeeded:**

```json
{
  "event": "item/login_succeeded",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}
```

### Exemplos de Conector

**connector/status_updated:**

```json
{
  "id": "201",
  "event": "connector/status_updated",
  "eventId": "4552bee0-b87f-48b5-896b-c23113839319",
  "connectorId": "201",
  "data": {
    "status": "UNSTABLE"
  }
}
```

### Exemplos de Transação

**transactions/deleted:**

```json
{
  "event": "transactions/deleted",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
  "accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
  "transactionIds": [
    "5a14feae-eaa7-423a-820c-6b83837c35b7",
    "786c7d98-6085-4879-9c7f-2255260e2436"
  ]
}
```

**transactions/updated:**

```json
{
  "event": "transactions/updated",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
  "accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
  "transactionIds": [
    "5a14feae-eaa7-423a-820c-6b83837c35b7",
    "786c7d98-6085-4879-9c7f-2255260e2436"
  ]
}
```

**transactions/created:**

```json
{
  "itemId": "de7bbf5a-abf2-47e4-94b1-586b36758423",
  "event": "transactions/created",
  "id": "de7bbf5a-abf2-47e4-94b1-586b36758423",
  "eventId": "4e69d62d-b7c8-4f01-b591-a1d8a94710b9",
  "accountId": "0d5a0de2-9c82-4ea2-af50-31643a632a33",
  "transactionsCount": 332,
  "transactionsMinDate": "2025-02-12T15:00:01.000Z",
  "transactionsCreatedAtFrom": "2025-02-13T17:21:53.719Z",
  "createdTransactionsLink": "https://api.pluggy.ai/v2/transactions?accountId=0d5a0de2-9c82-4ea2-af50-31643a632a33&createdAtFrom=2025-02-13T17:21:53.719Z&after=MjAyNS0wMi0xM1QxODowMjoxMS4wMDFafGZmZmZmZmZmLWZmZmYtZmZmZi1mZmZmLWZmZmZmZmZmZmZmZg%3D%3D"
}
```

`createdTransactionsLink` aponta para [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor), filtrado por `createdAtFrom` e com o cursor já definido: pagine conforme vem. Aplicações criadas antes de 2026-06-02 00:00 horário de Brasília (03:00 UTC) ainda recebem o link depreciado `/transactions` em `createdTransactionsLink` e o `/v2` em um campo extra, `createdTransactionsLinkV2`. Use `createdTransactionsLinkV2`: `/transactions` está depreciado e disponível apenas até 2026-12-31 (veja o [changelog](/changelog#2026.06-transition-to-cursor-pagination-on-the-transactions-endpoint)).

### Exemplos de Intenção de Pagamento

**payment_intent/created:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "paymentIntentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "event": "payment_intent/created",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0"
}
```

**payment_intent/completed:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "paymentIntentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "event": "payment_intent/completed",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "referenceId": "E33371172200009110200U70a27b2698"
}
```

**payment_intent/error:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "paymentIntentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "event": "payment_intent/error",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "referenceId": "E33371172200009110200U70a27b2698",
  "error": {
    "code": "REJECTED_BY_USER",
    "description": "O consentimento foi rejeitado pelo usuário.",
    "detail": "O usuário rejeitou a autorização do consentimento"
  }
}
```

### Exemplos de Solicitação de Pagamento

**payment_request/updated:**

```json
{
  "event": "payment_request/updated",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6",
  "clientId": "client-123",
  "status": "CANCELED"
}
```

### Exemplos de Pagamentos Programados

**scheduled_payment/created:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "scheduled_payment/created"
}
```

**scheduled_payment/completed:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "scheduled_payment/completed"
}
```

**scheduled_payment/error:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "scheduled_payment/error",
  "error": {
    "title": "Título do erro",
    "code": "Código do Erro",
    "description": "Descrição do erro"
  }
}
```

**scheduled_payment/canceled:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "scheduled_payment/canceled"
}
```

### Exemplos de Pagamentos Automáticos PIX

**automatic_pix_payment/created:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/created"
}
```

**automatic_pix_payment/completed:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/completed"
}
```

**automatic_pix_payment/error:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/error",
  "error": {
    "title": "Título do erro",
    "code": "Código do Erro",
    "description": "Descrição do erro"
  }
}
```

**automatic_pix_payment/canceled:**

```json
{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/canceled"
}
```

### Exemplos de Transferências Inteligentes

**smart_transfer_preauthorization/completed:**

```json
{
  "clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee8",
  "event": "smart_transfer_preauthorization/completed",
  "eventId": "8013240b-7c0a-409e-bf00-7fc586cc9196",
  "smartTransferPreauthorizationId": "f84e6e06-e0f9-4ab3-89f2-da062be65e7c",
  "status": "COMPLETED"
}
```

**smart_transfer_preauthorization/error:**

```json
{
  "clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee8",
  "event": "smart_transfer_preauthorization/error",
  "eventId": "54ceeb25-b9f7-4b90-8124-0cff66d1b2c3",
  "smartTransferPreauthorizationId": "3dd45002-52aa-44e8-a206-f6b99a293d9a",
  "status": "REJECTED",
  "error": {
    "code": "REJECTED_BY_USER",
    "description": "O consentimento foi rejeitado pelo usuário.",
    "detail": "O usuário rejeitou a autorização do consentimento"
  }
}
```

**smart_transfer_payment/completed:**

```json
{
  "clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee8",
  "event": "smart_transfer_payment/completed",
  "eventId": "0dfa6e5d-aee4-42b6-bd3b-e27e9c591339",
  "smartTransferPreauthorizationId": "f84e6e06-e0f9-4ab3-89f2-da062be65e73",
  "smartTransferPaymentId": "2afc828e-0dc2-4195-a774-145f7d7fc46c",
  "status": "PAYMENT_COMPLETED"
}
```

**smart_transfer_payment/error:**

```json
{
  "clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee6",
  "event": "smart_transfer_payment/error",
  "eventId": "59ff7a4a-d804-499b-a31c-7865014ba0ef",
  "smartTransferPreauthorizationId": "f84e6e06-e0f9-4ab3-89f2-da062be65e73",
  "smartTransferPaymentId": "b546ab61-f1cd-4cd4-b5bf-0073d9a9ee3a",
  "status": "PAYMENT_REJECTED",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "description": "A conta não tem saldo suficiente para realizar o pagamento.",
    "detail": "Saldo insuficiente."
  }
}
```

### Exemplos de PIX por Biometria

**pix_biometric_enrollment/authorized:**

```json
{
  "event": "pix_biometric_enrollment/authorized",
  "eventId": "8013240b-7c0a-409e-bf00-7fc586cc9196",
  "enrollmentId": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
  "customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
  "paymentRequestId": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e"
}
```

**pix_biometric_enrollment/revoked:**

```json
{
  "event": "pix_biometric_enrollment/revoked",
  "eventId": "54ceeb25-b9f7-4b90-8124-0cff66d1b2c3",
  "enrollmentId": "c91a5e2b-7d0f-4f3e-9a51-2f6b8e1d4c77",
  "customerId": "a2d4c1e8-5b7f-4c3a-9e2d-1f6b8c0d7e55",
  "paymentRequestId": "5b7e2c1d-3a4f-4e8b-9c6d-7f0a1b2c3d4e"
}
```

**pix_biometric_enrollment/error:**

```json
{
  "event": "pix_biometric_enrollment/error",
  "eventId": "59ff7a4a-d804-499b-a31c-7865014ba0ef",
  "enrollmentId": "3dd45002-52aa-44e8-a206-f6b99a293d9a",
  "customerId": null,
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b"
}
```

`paymentRequestId` é a solicitação de pagamento onde o pagador criou o vínculo. O evento não carrega status ou razão: recupere a matrícula com `GET /pix-biometric/enrollments/{id}` para obtê-los.

## Tratamento de notificações

Quando enviamos uma notificação de webhook, uma de duas coisas acontece:

1. **Sua API responde com um status `2XX` dentro de 10 segundos** → sucesso
2. **Sua API responde com qualquer outro status, ou não responde dentro de 10 segundos** → falha

### Cronograma de Tentativas

Tentamos entregar cada webhook até **3 vezes**:

| Tentativa | Quando |
| --- | --- |
| 1ª | Imediatamente |
| 2ª | ~15 minutos após a 1ª tentativa falhar |
| 3ª | ~2 horas após a 2ª tentativa falhar |

Se a 3ª tentativa falhar, a notificação não será entregue novamente automaticamente.

### Respostas que não tentamos novamente

Algumas respostas nos dizem que a solicitação nunca terá sucesso como enviada. Nesses casos, paramos após a primeira tentativa e não agendamos novas tentativas:

`400` · `401` · `403` · `404` · `405`

Qualquer outro resultado que não seja 2XX é tratado como temporário e recebe o cronograma completo de 3 tentativas acima, incluindo `408`, `429`, qualquer `5XX`, erros de conexão e timeouts. Não seguimos redirecionamentos: um `3XX` conta como uma tentativa falhada.

Se seu domínio resolver para um endereço IP privado ou reservado quando enviamos a notificação, ela não é entregue e não é tentada novamente.

<Callout variant="warning">
Se seu endpoint responder `400` enquanto está **temporariamente** quebrado — um bug ao analisar o payload, um deploy que deixa seu manipulador rejeitando solicitações válidas — essas notificações são descartadas após uma única tentativa e não voltarão por conta própria. Retorne um `5XX` para problemas temporários ou inesperados do lado do servidor, e reserve `4XX` para solicitações que você nunca aceitará.
</Callout>

<Callout variant="info" title="Exceção: eventos de item sensíveis ao tempo">
`item/waiting_user_input` e `item/login_succeeded` são sensíveis ao tempo: eles recebem 3 tentativas espaçadas em cerca de 6 minutos, e nunca usam o cronograma de 15 minutos / 2 horas. Após a 3ª tentativa, não são tentados novamente.
</Callout>

### Se todas as tentativas falharem

Você pode tentar novamente uma notificação manualmente a partir do Dashboard. Uma tentativa manual inicia um novo ciclo de até 3 tentativas, ~15 minutos de intervalo. A regra acima ainda se aplica: se seu endpoint continuar respondendo `400`, `401`, `403`, `404` ou `405`, a tentativa manual também para após uma tentativa — então conserte o endpoint primeiro, depois tente novamente.

### Respondendo a notificações

É obrigatório que sua API retorne 2XX logo após receber uma notificação, e então faça seu processamento após responder ao Pluggy. Dessa forma, se seu processamento levar mais de 10 segundos, não interpretaremos isso como uma falha, evitando assim tentativas indesejadas da mesma notificação.

Para todas as notificações de itens, esperamos que a primeira coisa que você faça ao processar o evento seja fazer um `GET /items/{id}` para recuperar as informações mais recentes relacionadas ao evento, em vez de processar a partir dos dados do payload do evento.

<Callout variant="info" title="Whitelist dos IPs do Pluggy">
Se você deseja adicionar medidas de segurança extras para fornecer filtragem de IP para nossas solicitações, deve colocar na lista branca os seguintes IPs:

`52.67.145.81`

Filtrar apenas por IP não prova que uma notificação é para você. Use isso junto com as verificações em [Verificando notificações](#verifying-notifications).
</Callout>

## Cabeçalhos do Webhook

Ao criar ou atualizar um webhook, você pode especificar um objeto `headers` para enviar cabeçalhos específicos em suas notificações de webhook. Recomendamos usá-lo para enviar um segredo que seu endpoint [verifica em cada solicitação](#verifying-notifications). Com a API, você pode adicionar cabeçalhos ao seu webhook assim:

```json
{
  "url": "example.com",
  "event": "all",
  "headers": {
    "Authorization": "Minha chave de API",
    "X-CLIENT-ID": "Alguma informação extra secreta"
  }
}
```

<Callout variant="info" title="Cabeçalhos no Dashboard">
Você também pode adicionar, substituir ou remover os cabeçalhos de um webhook no Dashboard: abra a aplicação e edite o webhook em **Webhooks**. Apenas o Proprietário da aplicação pode alterá-los. Os valores são somente para escrita lá: uma vez salvos, o Dashboard mostra os nomes dos cabeçalhos, mas nunca seus valores, então mantenha sua própria cópia do segredo.

Para os campos da API, veja [Webhook](/docs/reference/webhooks#webhook-resource) na referência da API.
</Callout>

Além dos seus cabeçalhos personalizados, uma entrega para uma aplicação com um [segredo de assinatura](#signing) carrega `X-Pluggy-Signature`. Ele é definido pelo Pluggy: um cabeçalho com esse nome em `headers` não define ou substitui. Um cabeçalho secreto apenas mostra que o chamador conhece o valor; a assinatura também prova que o Pluggy enviou a notificação e que seu corpo não foi alterado. Veja [Segurança do Webhook](/docs/developer-tools/webhook-security).

## Verificando notificações

Seu endpoint de webhook é publicamente acessível, então trate cada solicitação como não confiável até que você a verifique. Vir de um IP do Pluggy não é suficiente. Faça essas verificações em cada solicitação:

1. **Exija um segredo.** Registre seu webhook com um segredo em [`headers`](#webhook-headers), e responda `401` a qualquer solicitação que não o carregue. Isso se aplica a webhooks criados com `POST /webhooks`: um `webhookUrl` definido em um Item ou um Connect Token não envia cabeçalhos personalizados, então não exija um cabeçalho secreto naquela URL.
2. **Verifique `clientId`.** O Pluggy define este campo para a aplicação à qual o webhook pertence. Ignore qualquer notificação cujo `clientId` não seja um dos seus aplicativos. Isso filtra webhooks registrados por outras contas, mas não autentica a solicitação.
3. **Verifique a assinatura.** Se sua aplicação tiver um [segredo de assinatura](#signing), verifique `X-Pluggy-Signature` e responda `401` quando não corresponder. É a única verificação que prova que o corpo não foi alterado, e também cobre um `webhookUrl` definido em um Item ou um Connect Token.

Um `webhookUrl` definido em um Item ou um Connect Token não envia cabeçalhos personalizados, e uma solicitação direta pode carregar qualquer `clientId`. Assine seus webhooks, ou prefira um webhook criado com `POST /webhooks`. Se você mantiver um `webhookUrl`, pode adicionar um token imprevisível à sua string de consulta e verificá-lo em cada solicitação, mas a URL completa é visível no Dashboard e pode aparecer em logs, e mudar o token significa atualizar a URL. Em qualquer caso, trate cada notificação apenas como um sinal: leia os dados com sua chave de API, por exemplo, com `GET /items/{id}`, e não aja com base no payload.

<Callout variant="warning" title="Rotacionando o segredo do cabeçalho">
Um `401` não é tentado novamente automaticamente, então uma notificação rejeitada durante uma rotação não é entregue novamente. Aceite tanto o segredo antigo quanto o novo até que você tenha atualizado o webhook com `PATCH /webhooks/{id}`, e só então pare de aceitar o antigo. Isso diz respeito ao segredo nos `headers` do seu webhook. Um [segredo de assinatura](#signing) é rotacionado de forma diferente, porque o Pluggy muda para o novo assim que você o regenera: siga [Rotacionando o segredo](/docs/developer-tools/webhook-security#rotating-the-secret).
</Callout>

## Assinatura

Você pode fazer com que o Pluggy assine cada webhook de uma aplicação com HMAC-SHA256. No Dashboard, abra a aplicação e, em **Webhooks**, gere um segredo de assinatura (apenas o Proprietário da equipe pode). A partir de então, cada entrega carrega:

```
X-Pluggy-Signature: t=<segundos unix>,v1=<hex HMAC-SHA256 de "<t>.<corpo bruto>">
```

Verifique-o sobre o corpo da solicitação bruta, com uma comparação em tempo constante, e rejeite um `t` mais antigo que 5 minutos. [Segurança do Webhook](/docs/developer-tools/webhook-security#4-verify-the-signature) tem o formato completo, código de verificação em Node.js e Python, e como rotacionar o segredo sem rejeitar notificações.