# Webhook

Um webhook é uma URL HTTPS sua que recebe um `POST` com um corpo JSON quando um evento acontece. Duas maneiras de se inscrever:

- **Um recurso Webhook** — [`POST /webhooks`](/reference/webhook/webhooks-create) com um `url` e um `event`. Entrega esse evento para cada recurso da aplicação.
- **`webhookUrl` em um recurso** — definido ao criar um Item, um Connect Token ou uma Solicitação de Pagamento. Entrega cada evento, mas apenas para esse recurso (ou os Items criados com esse token).

## Recurso Webhook

```http
POST https://api.pluggy.ai/webhooks
X-API-KEY: {apiKey}
Content-Type: application/json

{
  "url": "https://example.com/pluggy",
  "event": "item/updated",
  "headers": { "X-CLIENT-ID": "…" }
}
```

| Campo | Obrigatório | Significado |
| --- | --- | --- |
| `url` | sim | Apenas HTTPS. `localhost` não é aceito — use um túnel como ngrok enquanto desenvolve. |
| `event` | sim | Um evento das tabelas abaixo, `item/all` para cada evento de Item, ou `all` para tudo. |
| `headers` | não | Enviado com cada entrega para esta URL — a maneira de passar uma chave de API que seu endpoint requer. Apenas configurável através da API, nunca mostrado no dashboard. |

Endpoints: [`GET /webhooks`](/reference/webhook/webhooks-list), [`POST /webhooks`](/reference/webhook/webhooks-create), e recuperar, atualizar e deletar em [`/webhooks/{id}`](/reference/webhook).

## Eventos

**Dados**

| Evento | Dispara quando |
| --- | --- |
| `item/created` | Um Item foi criado e conectado com sucesso. |
| `item/updated` | Um Item foi atualizado e sincronizado com sucesso. |
| `item/deleted` | Um Item foi deletado. |
| `item/error` | Uma execução terminou em erro; `USER_AUTHORIZATION_PENDING` também dispara isso. |
| `item/waiting_user_input` | O Item precisa de entrada do usuário (MFA) para continuar. |
| `item/waiting_user_action` | O Item precisa que o usuário atue em seu dispositivo — autorizar no aplicativo do banco, escanear um código QR. |
| `item/login_succeeded` | O login na instituição foi bem-sucedido; a coleta de dados está em andamento. |
| `connector/status_updated` | Um conector mudou de status (`ONLINE`, `UNSTABLE`, `OFFLINE`). Transporta `connectorId`. |
| `transactions/created` | Novas transações após uma atualização; transporta `createdTransactionsLink` para buscá-las. |
| `transactions/updated` | Transações mudaram após uma atualização; transporta seus ids. |
| `transactions/deleted` | Transações removidas após uma atualização; transporta seus ids. |

Eventos de transação disparam apenas quando algo muda; uma atualização sem novas transações não emite `transactions/created`.

**Pagamentos**

| Evento | Dispara quando |
| --- | --- |
| `payment_intent/created` | Uma intenção de pagamento foi criada para uma solicitação. |
| `payment_intent/waiting_payer_authorization` | A intenção precisa da autorização do pagador. |
| `payment_intent/completed` | A intenção foi concluída. |
| `payment_intent/error` | A intenção falhou. |
| `payment_request/updated` | Uma solicitação de pagamento mudou de status. |
| `scheduled_payment/created`, `/completed`, `/error`, `/canceled` | Um pagamento agendado de uma autorização foi movido. |
| `scheduled_payment/all_created`, `/all_completed` | Cada pagamento agendado de uma autorização foi criado / concluído. |
| `automatic_pix_payment/created`, `/completed`, `/error`, `/canceled` | Um pagamento de uma solicitação de PIX Automático foi movido. |
| `smart_transfer_preauthorization/completed`, `/error` | Uma pré-autorização de Transferência Inteligente foi aprovada ou falhou. |
| `smart_transfer_payment/completed`, `/error` | Um pagamento de Transferência Inteligente foi liquidado ou falhou. |

## Payload

Cada notificação carrega:

| Campo | Significado |
| --- | --- |
| `event` | O nome do evento. |
| `eventId` | Identifica o evento; o mesmo valor quando um evento é entregue a várias URLs. |
| `triggeredBy` | `USER` (um Connect Token, por exemplo, o widget), `CLIENT` (uma Chave de API, por exemplo, um `PATCH`), `SYNC` (auto-sync) ou `INTERNAL` (suporte Pluggy). Ausente em `item/deleted`, `connector/status_updated` e `transactions/deleted`. |
| o id da entidade | `itemId` em eventos de Item, `transactionIds` em eventos de transação, `connectorId` em eventos de conector, e assim por diante por evento. |
| `clientUserId` | Somente em eventos `item/*` — o valor definido através das `options` do Connect Token. Não em `transactions/*`: mapeie-os para seu usuário através de `itemId`. |

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

## Entrega e tentativas

Uma entrega é bem-sucedida quando seu endpoint responde `2xx` **dentro de 5 segundos**. Responda primeiro, processe depois — um manipulador lento é contado como uma falha e tentado novamente.

Em caso de falha: três tentativas consecutivas; se todas falharem, mais três após 1 hora; se essas falharem, uma última tentativa de três após 2 horas. Até **9 entregas** de um evento. Exceção: `item/login_succeeded` recebe apenas as três tentativas consecutivas, sem tentativas atrasadas.

Leia o guia: [Webhook](/docs/developer-tools/webhooks-ref) — exemplos de payload por evento e solução de problemas.