Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs
POST/webhooks

Criar

Creates a webhook attached to the specific event and provides the notification url. **Signature.** If your application has a webhook signing secret (generated, regenerated or removed by the team Owner in the Dashboard, under Applications → Configure → Webhooks), every delivery carries an `X-Pluggy-Signature: t=<unix timestamp in seconds>,v1=<lowercase hex>` header, set by Pluggy. `v1` is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the full secret (`whsec_` plus 64 hex characters, prefix included). To verify, compute it over the raw body before any JSON parsing, compare it to `v1` in constant time, and reject a `t` more than 5 minutes away from your clock; every attempt, retries included, is signed again with a fresh `t`. Applications without a secret receive deliveries without the header, as before. A change to the secret takes a few seconds to take effect: right after regenerating, a delivery can still be signed with the previous secret (accept both for a while), and right after removing it, a delivery already on its way can arrive unsigned. See [Webhook security](https://docs.pluggy.ai/docs/developer-tools/webhook-security).

Request Body

required

Expects the following webhooks parameters: event: One of the event types that are supported. url: An https url that will receive the POST of the event. The host must be a publicly resolvable domain — IP literals, localhost, *.localhost, *.local, *.internal, and hostnames that resolve to a private/loopback/link-local/reserved range are rejected. headers: optional key-value pairs to send with the POST of the event.

object
urlrequiredstring

Public https url that will receive the POST of the event. It must use the default port (443), can't include a username or password, can't be longer than 2048 characters, and its host must be a domain name (not an IP address, localhost or an internal name) that resolves only to public IP addresses.

eventrequiredstring

Evento ao qual o webhook se inscreve. Use `all` para receber todos os eventos para o cliente. Os eventos são agrupados por tópico: **item/** – Ciclo de vida de um item (uma conexão com uma instituição financeira). - `item/created`: um novo item foi criado. - `item/updated`: o item terminou uma execução com novos dados. - `item/error`: a execução terminou com um erro (veja o campo `error` do payload). - `item/deleted`: o item foi deletado. - `item/waiting_user_input`: o item precisa de credenciais adicionais/MFA do usuário final. - `item/waiting_user_action`: o item precisa que o usuário final realize uma ação do lado da instituição. - `item/login_succeeded`: as credenciais foram aceitas pela instituição (os dados ainda podem estar sincronizando). **connector/** – Eventos em nível de conector. - `connector/status_updated`: o status de saúde de um conector mudou (ONLINE/OFFLINE/UNSTABLE). **transactions/** – Ciclo de vida de transações de conta. - `transactions/created` / `transactions/updated` / `transactions/deleted`: uma transação foi inserida, modificada ou removida durante uma execução de item. **payment_intent/** – Fluxo de Iniciação de Pagamento (PIX único). - `payment_intent/created`: uma intenção de pagamento foi criada. - `payment_intent/completed`: o pagamento foi confirmado pela instituição. - `payment_intent/waiting_payer_authorization`: o pagador ainda precisa autorizar o pagamento. - `payment_intent/error`: o pagamento foi rejeitado ou falhou. **payment_request/** – Estado agregado de solicitação de pagamento. - `payment_request/updated`: o status geral de uma solicitação de pagamento mudou. **scheduled_payment/** – Pagamentos agendados (recorrentes ou futuros). - `scheduled_payment/created` / `completed` / `error` / `canceled`: ciclo de vida de um único pagamento agendado. - `scheduled_payment/all_created` / `scheduled_payment/all_completed`: emitido uma vez quando cada pagamento agendado em uma série atinge o mesmo estado terminal. **boleto/** – Atualizações de status do boleto. - `boleto/updated`: os dados do boleto foram atualizados (por exemplo, pago, expirado, valor alterado). **automatic_pix_payment/** – Pagamentos individuais recorrentes de PIX (PIX Automático). - `automatic_pix_payment/created`: um novo pagamento recorrente foi agendado. - `automatic_pix_payment/completed`: o pagamento recorrente foi confirmado. - `automatic_pix_payment/error`: o pagamento recorrente falhou. - `automatic_pix_payment/canceled`: o pagamento recorrente foi cancelado (pelo usuário, expiração ou consentimento revogado). **smart_transfer_preauthorization/** – Pré-autorização de Transferência Inteligente (configuração de consentimento). - `smart_transfer_preauthorization/completed`: a pré-autorização foi aceita. - `smart_transfer_preauthorization/error`: a pré-autorização falhou. **smart_transfer_payment/** – Pagamentos individuais de Transferência Inteligente executados sob uma pré-autorização ativa. - `smart_transfer_payment/completed`: a transferência foi bem-sucedida. - `smart_transfer_payment/error`: a transferência falhou.

allitem/createditem/updateditem/erroritem/deleteditem/waiting_user_inputitem/waiting_user_actionitem/login_succeededconnector/status_updatedtransactions/createdtransactions/updatedtransactions/deletedpayment_intent/createdpayment_intent/completedpayment_intent/waiting_payer_authorizationpayment_intent/errorpayment_request/updatedscheduled_payment/createdscheduled_payment/completedscheduled_payment/errorscheduled_payment/canceledscheduled_payment/all_completedscheduled_payment/all_createdboleto/updatedautomatic_pix_payment/createdautomatic_pix_payment/completedautomatic_pix_payment/errorautomatic_pix_payment/canceledsmart_transfer_preauthorization/completedsmart_transfer_preauthorization/errorsmart_transfer_payment/completedsmart_transfer_payment/errorpix_biometric_enrollment/authorizedpix_biometric_enrollment/revokedpix_biometric_enrollment/error
headersobject

HTTP headers that will be included in the webhook notifications (useful for things like authorization). A header named `X-Pluggy-Signature` here does not set or override the signature header Pluggy adds.

Example

json
{
  "url": "string",
  "event": "all",
  "headers": null
}

Responses

201Webhook criado
object

A webhook subscription. Each delivery is an HTTP POST of the event to `url`, with the custom `headers` and, when the application has a webhook signing secret, the `X-Pluggy-Signature` header (see [Webhook security](https://docs.pluggy.ai/docs/developer-tools/webhook-security)).

idrequiredstring

Identificador UUID para a entidade

urlrequiredstring

Url para ser notificado sobre alterações de item

eventrequiredstring

Evento ao qual o webhook se inscreve. Use `all` para receber todos os eventos para o cliente. Os eventos são agrupados por tópico: **item/** – Ciclo de vida de um item (uma conexão com uma instituição financeira). - `item/created`: um novo item foi criado. - `item/updated`: o item terminou uma execução com novos dados. - `item/error`: a execução terminou com um erro (veja o campo `error` do payload). - `item/deleted`: o item foi deletado. - `item/waiting_user_input`: o item precisa de credenciais adicionais/MFA do usuário final. - `item/waiting_user_action`: o item precisa que o usuário final realize uma ação do lado da instituição. - `item/login_succeeded`: as credenciais foram aceitas pela instituição (os dados ainda podem estar sincronizando). **connector/** – Eventos em nível de conector. - `connector/status_updated`: o status de saúde de um conector mudou (ONLINE/OFFLINE/UNSTABLE). **transactions/** – Ciclo de vida de transações de conta. - `transactions/created` / `transactions/updated` / `transactions/deleted`: uma transação foi inserida, modificada ou removida durante uma execução de item. **payment_intent/** – Fluxo de Iniciação de Pagamento (PIX único). - `payment_intent/created`: uma intenção de pagamento foi criada. - `payment_intent/completed`: o pagamento foi confirmado pela instituição. - `payment_intent/waiting_payer_authorization`: o pagador ainda precisa autorizar o pagamento. - `payment_intent/error`: o pagamento foi rejeitado ou falhou. **payment_request/** – Estado agregado de solicitação de pagamento. - `payment_request/updated`: o status geral de uma solicitação de pagamento mudou. **scheduled_payment/** – Pagamentos agendados (recorrentes ou futuros). - `scheduled_payment/created` / `completed` / `error` / `canceled`: ciclo de vida de um único pagamento agendado. - `scheduled_payment/all_created` / `scheduled_payment/all_completed`: emitido uma vez quando cada pagamento agendado em uma série atinge o mesmo estado terminal. **boleto/** – Atualizações de status do boleto. - `boleto/updated`: os dados do boleto foram atualizados (por exemplo, pago, expirado, valor alterado). **automatic_pix_payment/** – Pagamentos individuais recorrentes de PIX (PIX Automático). - `automatic_pix_payment/created`: um novo pagamento recorrente foi agendado. - `automatic_pix_payment/completed`: o pagamento recorrente foi confirmado. - `automatic_pix_payment/error`: o pagamento recorrente falhou. - `automatic_pix_payment/canceled`: o pagamento recorrente foi cancelado (pelo usuário, expiração ou consentimento revogado). **smart_transfer_preauthorization/** – Pré-autorização de Transferência Inteligente (configuração de consentimento). - `smart_transfer_preauthorization/completed`: a pré-autorização foi aceita. - `smart_transfer_preauthorization/error`: a pré-autorização falhou. **smart_transfer_payment/** – Pagamentos individuais de Transferência Inteligente executados sob uma pré-autorização ativa. - `smart_transfer_payment/completed`: a transferência foi bem-sucedida. - `smart_transfer_payment/error`: a transferência falhou.

allitem/createditem/updateditem/erroritem/deleteditem/waiting_user_inputitem/waiting_user_actionitem/login_succeededconnector/status_updatedtransactions/createdtransactions/updatedtransactions/deletedpayment_intent/createdpayment_intent/completedpayment_intent/waiting_payer_authorizationpayment_intent/errorpayment_request/updatedscheduled_payment/createdscheduled_payment/completedscheduled_payment/errorscheduled_payment/canceledscheduled_payment/all_completedscheduled_payment/all_createdboleto/updatedautomatic_pix_payment/createdautomatic_pix_payment/completedautomatic_pix_payment/errorautomatic_pix_payment/canceledsmart_transfer_preauthorization/completedsmart_transfer_preauthorization/errorsmart_transfer_payment/completedsmart_transfer_payment/errorpix_biometric_enrollment/authorizedpix_biometric_enrollment/revokedpix_biometric_enrollment/error
disabledAtstring (date-time) | null

Data em que o webhook foi desativado

createdAtstring (date-time)

Data em que foi criado

updatedAtstring (date-time)

Data da última atualização

headersrequiredobject

Custom headers sent with each webhook delivery. Always present; an empty object when none are configured. A header named `X-Pluggy-Signature` here does not set or override the signature header Pluggy adds.

<key>string

Example response

json
{
  "id": "string",
  "url": "string",
  "event": "all",
  "disabledAt": "2024-01-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "headers": {
    "<key>": "string"
  }
}
curl -X POST \
'https://api.pluggy.ai/webhooks' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: YOUR_API_KEY' \
-d '{ "url": "string", "event": "all", "headers": null }'
Resposta de exemplo
{
"id": "string",
"url": "string",
"event": "all",
"disabledAt": "2024-01-01T00:00:00Z",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"headers": {
"<key>": "string"
}
}