# 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 ou um Connect Token. Entrega cada evento, mas apenas para esse recurso (ou os Itens 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 | Uma URL HTTPS pública — veja [requisitos de URL](#url-requirements). `localhost` não é aceito — use um túnel como ngrok durante o desenvolvimento. |
| `event` | sim | Um evento das tabelas abaixo, ou `all` para tudo. Não há curinga por produto: para receber todos os eventos de Item, registre `all` ou um webhook por evento. |
| `headers` | não | Enviado com cada entrega para esta URL — a maneira de passar um secret que seu endpoint [verifica](/docs/developer-tools/webhooks-ref#verifying-notifications). Também pode ser definido no Dashboard pelo Proprietário da aplicação, que mostra os nomes dos cabeçalhos, mas nunca seus valores. Para provar que uma entrega veio da Pluggy inalterada, use a [assinatura](/docs/developer-tools/webhook-security#4-verify-the-signature). |

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

### Requisitos de URL

A `url` de um webhook — e o `webhookUrl` de um Item ou um Connect Token — deve ser um endpoint HTTPS público:

| Regra | Exemplo rejeitado |
| --- | --- |
| Apenas HTTPS | `http://example.com/pluggy` |
| Apenas porta HTTPS padrão (443) | `https://example.com:8443/pluggy` |
| Sem nome de usuário ou senha na URL | `https://user:pass@example.com/pluggy` |
| O host é um nome de domínio, não um endereço IP | `https://203.0.113.10/pluggy` |
| Sem `localhost` ou nomes internos (`.local`, `.internal`, `.localdomain`, `.home.arpa`) | `https://api.internal/pluggy` |
| O domínio resolve apenas para endereços IP públicos | um domínio que resolve para `10.0.0.5` |
| No máximo 2048 caracteres | — |

Túneis e serviços de inspeção de requisições como ngrok ou webhook.site são aceitos.

Uma URL que quebra uma regra falha com `400`, e a mensagem nomeia a regra:

```json
{
  "code": 400,
  "message": "Webhook url must use the default https port"
}
```

<Callout variant="info">
Webhooks registrados antes de uma regra existir continuam recebendo eventos, mas você não pode atualizar ou reabilitar um até que sua `url` siga todas as regras.
</Callout>

## 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 excluído. |
| `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 — autorize no aplicativo do banco, escaneie 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 mudou; 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. |
| `clientId` | O ID do Cliente da aplicação a qual o webhook pertence. Ignore uma notificação cujo `clientId` não seja seu. |
| `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 esses para seu usuário através de `itemId`. |

```json
{
  "event": "item/updated",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "clientId": "65a8c757-ef2c-4bc3-94ed-99218f6a0ee8",
  "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 10 segundos**. Responda primeiro, processe depois — um manipulador lento é contado como uma falha e tentado novamente.

Em caso de falha: **até 3 tentativas** no total — imediatamente, ~15 minutos após a primeira falha, e então ~2 horas após a segunda. Depois disso, o evento é descartado. Status `400`, `401`, `403`, `404` e `405` nunca são tentados novamente. Exceção: `item/login_succeeded` e `item/waiting_user_input` recebem suas 3 tentativas ~6 minutos de intervalo, nunca a espera de 2 horas.

Redirecionamentos não são seguidos: um `3xx` conta como uma falha. Se o domínio resolver para um endereço IP privado ou reservado quando a notificação for enviada, não será entregue e não será tentado novamente.

Quando a aplicação tem um secret de assinatura, cada entrega carrega `X-Pluggy-Signature` — veja [Segurança do Webhook](/docs/developer-tools/webhook-security#4-verify-the-signature).

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