PluggyDocs
POST/webhooks

Create

Creates a webhook attached to the specific event and provides the notification url

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
eventrequiredstring

Event the webhook subscribes to. Use `all` to receive every event for the client. Events are grouped by topic: **item/** – Lifecycle of an item (a connection to a financial institution). - `item/created`: a new item was created. - `item/updated`: the item finished an execution with new data. - `item/error`: the execution finished with an error (see the payload's `error` field). - `item/deleted`: the item was deleted. - `item/waiting_user_input`: the item needs additional credentials/MFA from the end user. - `item/waiting_user_action`: the item needs the end user to perform an action on the institution side. - `item/login_succeeded`: the credentials were accepted by the institution (data may still be syncing). **connector/** – Connector-level events. - `connector/status_updated`: a connector's health status changed (ONLINE/OFFLINE/UNSTABLE). **transactions/** – Account transaction lifecycle. - `transactions/created` / `transactions/updated` / `transactions/deleted`: a transaction was inserted, modified or removed during an item execution. **payment_intent/** – Payment Initiation flow (single PIX). - `payment_intent/created`: a payment intent was created. - `payment_intent/completed`: the payment was confirmed by the institution. - `payment_intent/waiting_payer_authorization`: the payer still needs to authorize the payment. - `payment_intent/error`: the payment was rejected or failed. **payment_request/** – Aggregate payment request state. - `payment_request/updated`: the overall status of a payment request changed. **scheduled_payment/** – Scheduled (recurring or future) payments. - `scheduled_payment/created` / `completed` / `error` / `canceled`: lifecycle of a single scheduled payment. - `scheduled_payment/all_created` / `scheduled_payment/all_completed`: emitted once when every scheduled payment in a series reaches the same terminal state. **boleto/** – Boleto status updates. - `boleto/updated`: the boleto data was updated (e.g. paid, expired, amount changed). **automatic_pix_payment/** – Recurring PIX (PIX Automático) individual payments. - `automatic_pix_payment/created`: a new recurring payment was scheduled. - `automatic_pix_payment/completed`: the recurring payment was confirmed. - `automatic_pix_payment/error`: the recurring payment failed. - `automatic_pix_payment/canceled`: the recurring payment was canceled (by user, expiration or revoked consent). **smart_transfer_preauthorization/** – Smart Transfer pre-authorization (consent setup). - `smart_transfer_preauthorization/completed`: the pre-authorization was accepted. - `smart_transfer_preauthorization/error`: the pre-authorization failed. **smart_transfer_payment/** – Smart Transfer individual payments executed under an active pre-authorization. - `smart_transfer_payment/completed`: the transfer was successful. - `smart_transfer_payment/error`: the transfer failed.

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/error
headersobject

HTTP headers that will be included in the webhook notifications (useful for things like authorization)

Example

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

Responses

201Created webhook
object
idrequiredstring

UUID identifier for the entity

urlrequiredstring

Url to be notified of item changes

eventrequiredstring

Event the webhook subscribes to. Use `all` to receive every event for the client. Events are grouped by topic: **item/** – Lifecycle of an item (a connection to a financial institution). - `item/created`: a new item was created. - `item/updated`: the item finished an execution with new data. - `item/error`: the execution finished with an error (see the payload's `error` field). - `item/deleted`: the item was deleted. - `item/waiting_user_input`: the item needs additional credentials/MFA from the end user. - `item/waiting_user_action`: the item needs the end user to perform an action on the institution side. - `item/login_succeeded`: the credentials were accepted by the institution (data may still be syncing). **connector/** – Connector-level events. - `connector/status_updated`: a connector's health status changed (ONLINE/OFFLINE/UNSTABLE). **transactions/** – Account transaction lifecycle. - `transactions/created` / `transactions/updated` / `transactions/deleted`: a transaction was inserted, modified or removed during an item execution. **payment_intent/** – Payment Initiation flow (single PIX). - `payment_intent/created`: a payment intent was created. - `payment_intent/completed`: the payment was confirmed by the institution. - `payment_intent/waiting_payer_authorization`: the payer still needs to authorize the payment. - `payment_intent/error`: the payment was rejected or failed. **payment_request/** – Aggregate payment request state. - `payment_request/updated`: the overall status of a payment request changed. **scheduled_payment/** – Scheduled (recurring or future) payments. - `scheduled_payment/created` / `completed` / `error` / `canceled`: lifecycle of a single scheduled payment. - `scheduled_payment/all_created` / `scheduled_payment/all_completed`: emitted once when every scheduled payment in a series reaches the same terminal state. **boleto/** – Boleto status updates. - `boleto/updated`: the boleto data was updated (e.g. paid, expired, amount changed). **automatic_pix_payment/** – Recurring PIX (PIX Automático) individual payments. - `automatic_pix_payment/created`: a new recurring payment was scheduled. - `automatic_pix_payment/completed`: the recurring payment was confirmed. - `automatic_pix_payment/error`: the recurring payment failed. - `automatic_pix_payment/canceled`: the recurring payment was canceled (by user, expiration or revoked consent). **smart_transfer_preauthorization/** – Smart Transfer pre-authorization (consent setup). - `smart_transfer_preauthorization/completed`: the pre-authorization was accepted. - `smart_transfer_preauthorization/error`: the pre-authorization failed. **smart_transfer_payment/** – Smart Transfer individual payments executed under an active pre-authorization. - `smart_transfer_payment/completed`: the transfer was successful. - `smart_transfer_payment/error`: the transfer failed.

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/error
disabledAtstring (date-time)

Date when the webhook was disabled

createdAtstring (date-time)

Date when it was created

updatedAtstring (date-time)

Date of the last update

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

Code Examples

bash
curl -X POST 'https://api.pluggy.ai/webhooks' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{}'

Try It