PluggyDocs

Webhook

Learn about the webhooks sent by Pluggy to create a reactive integration to data and payment changes.

Webhook#

In this guide we will cover the webhooks that are sent by Pluggy to create a reactive integration to changes. This will cover both data and payment integrations.

A Webhook is a tool that allows you to receive a notification for a certain event. It allows you to set up an HTTPS URL in our platform for certain events, and you will receive a JSON POST event at that URL, with specific event data.

To subscribe to Webhook events, you can either:

  • Create a Webhook instance directly, or
  • Specify the webhookUrl parameter (with a valid HTTPS URL), when:
    • creating an Item,
    • creating a Connect Token, or
    • creating a Payment Request

If you create a Webhook instance directly, you'll be subscribing to all the cases of events of the specified event type. Instead, if you do it by specifying the webhookUrl when creating an Item, or creating a Connect Token, you'll be notified about all the events, but only related to that specific resource. Which is, either to that Item specifically, or to the related item(s) created using that Connect Token.

Data Events#

We support registering for the following events when consuming Pluggy's data endpoints.

EventDescription
item/createdAn item was created and finished connecting successfully.
item/updatedAn item was updated and synced successfully.
item/deletedAn item was deleted successfully.
item/errorAn item has encountered errors in its execution. The case of USER_AUTHORIZATION_PENDING will also trigger this event.
item/waiting_user_inputAn item is blocked waiting for user input to continue.
item/waiting_user_actionAn item is blocked waiting for the user to approve an action on their device (e.g., authorize access in the banking app or scan a QR code).
item/login_succeededAn item has successfully logged in to the provider and it's collecting the data.
connector/status_updatedA connector has changed status (ONLINE/UNSTABLE/OFFLINE). This event informs the affected connector ID and updated status. Check the Connectors endpoint to see all connectors and their IDs.
transactions/deletedIDs of deleted transactions after merge data on item update.
transactions/createdReceive this webhook event, and use the createdTransactionsLink page to access all the transactions available and insert them in your data source.
transactions/updatedIDs of updated transactions after merge data on item update. After receiving this webhook, it's recommended to get the full transactions data using the transactions endpoint with the ids parameter.

Transactions webhooks are only fired when there is a data change. If there aren't any transactions, it won't fire a transactions/created event.

Payment Events#

We support registering for the following events when consuming Pluggy's payment endpoints.

Payment Intent#

EventDescription
payment_intent/createdID of payment intent created by the user, with paymentRequestId.
payment_intent/completedID of payment intent completed successfully by the user, with paymentRequestId.
payment_intent/waiting_payer_authorizationID of payment intent when it needs additional authorization.
payment_intent/errorID of payment intent when it has an error during the flow, with paymentRequestId.
payment_request/updatedPayment request status has changed.

Scheduled Payment#

EventDescription
scheduled_payment/createdIDs of the scheduled payment authorization.
scheduled_payment/completedA single payment of the authorization has been made.
scheduled_payment/errorPayment not completed, finished with error.
scheduled_payment/canceledPayment canceled by the user or the client.

Automatic PIX Payment#

EventDescription
automatic_pix_payment/createdA payment was scheduled for an automatic PIX payment request.
automatic_pix_payment/completedA scheduled payment associated with an automatic PIX payment request was completed successfully.
automatic_pix_payment/errorA scheduled payment associated to an automatic PIX payment request ended with error.
automatic_pix_payment/canceledA scheduled payment associated to an automatic PIX payment request was cancelled.

Smart Transfer#

EventDescription
smart_transfer_preauthorization/completedA smart transfer preauthorization was approved by a user.
smart_transfer_preauthorization/errorThere was an error during the smart transfer preauthorization approval. For example, when the user rejects the consent.
smart_transfer_payment/completedA smart transfer payment was completed.
smart_transfer_payment/errorThere was an error settling the smart transfer payment. For example, when the account doesn't have enough balance.

To register for a specific event, you will have to send the desired event to listen only to those webhook events.

Alternatively, you can just use the option all to receive all events associated.

We only accept HTTPS URLs. Localhost URLs are not allowed; you will have to provide an HTTPS URL using ngrok or other tools to provide public, secure URLs.

Tip: To test this functionality, you can use RequestCatcher, which is a tool that will just receive our notification and show you the payload. You can easily create a catcher with just a name in seconds.

Payload parameters#

When doing the POST request, all webhooks will send the following parameters in JSON format:

  • event: event's name (item/created, item/updated, item/error, etc.)
  • eventId: identifier of the event itself. It should be the same for one event when it is sent to many endpoints.
  • clientUserId: client user id
  • triggeredBy: who triggered the event (for all events except item/deleted, connector/status_updated and transactions/deleted). Possible values:
    • USER: an end user triggered the event with a Connect Token (for example, from Pluggy Connect)
    • CLIENT: a client triggered the event with an API Key (for example, by running PATCH on an Item)
    • SYNC: Auto-sync triggered the event
    • INTERNAL: It was triggered by someone from Pluggy's support team

Depending on the event type, the entity ID is sent. For example, for items, itemId. In transactions, transactionIds, and in connectors, connectorId.

Item examples#

item/created:

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

item/updated:

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

item/deleted:

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

item/error:

{
  "event": "item/error",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "d161a74a-8bc8-4093-88de-724312969b0d",
  "error": {
    "code": "USER_INPUT_TIMEOUT",
    "message": "User requested input had expired",
    "parameter": "token"
  },
  "triggeredBy": "USER",
  "clientUserId": "client-user-id"
}

item/waiting_user_input:

{
  "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:

{
  "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:

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

Connector examples#

connector/status_updated:

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

Transaction examples#

transactions/deleted:

{
  "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:

{
  "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:

{
  "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/transactions?accountId=0d5a0de2-9c82-4ea2-af50-31643a632a33&createdAtFrom=2025-02-13T17:21:53.719Z"
}

Payment Intent examples#

payment_intent/created:

{
  "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:

{
  "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:

{
  "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": "The consent was rejected by the user.",
    "detail": "O usuário rejeitou a autorização do consentimento"
  }
}

Payment Request examples#

payment_request/updated:

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

Scheduled Payments examples#

scheduled_payment/created:

{
  "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:

{
  "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:

{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "scheduledPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "scheduled_payment/error",
  "error": {
    "title": "Title of the error",
    "code": "Error Code",
    "description": "Error description"
  }
}

scheduled_payment/canceled:

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

Automatic PIX Payments examples#

automatic_pix_payment/created:

{
  "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:

{
  "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:

{
  "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": "Title of the error",
    "code": "Error Code",
    "description": "Error description"
  }
}

automatic_pix_payment/canceled:

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

Smart Transfers examples#

smart_transfer_preauthorization/completed:

{
  "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:

{
  "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": "The consent was rejected by the user.",
    "detail": "O usuário rejeitou a autorização do consentimento"
  }
}

smart_transfer_payment/completed:

{
  "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:

{
  "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": "The account doesn't have enough balance to perform the payment.",
    "detail": "Saldo insuficiente."
  }
}

Handling notifications#

When we send you a webhook notification, two things can happen:

  1. Your API responds 2XX in less than 5 seconds (success)
  2. Your API responds with a different status, or it does not respond in 5 seconds (failure)

We attempt to deliver each webhook up to three times in a row.

If delivery still fails, we retry again after 1 hour, with three more consecutive attempts. If it continues to fail, we make a final retry 2 hours later, again with three attempts.

In total, a webhook may be sent up to 9 times (initial attempt + retries).

Exception: The item/login_succeeded webhook will be sent just three times in a row but there are no backoff retries after 1 and 2 hours.

It's mandatory that your API returns 2XX right after receiving a notification and then does its processing after responding to Pluggy. This way, if your processing takes more than 5 seconds, we will not interpret it as a failure, therefore avoiding unwanted retries of the same notification.

For all items notifications, we expect that the first thing you do when processing the event is to do a GET /items/{id} to recover the latest information related to the event, instead of processing from the event's payload data.

Whitelisting Pluggy's IPs

If you want to add extra security measures to provide IP filtering to our requests, you should whitelist the following IPs:

52.67.145.81

Webhook headers#

When creating a webhook, you can specify a headers object to send specific headers in your webhook notifications. This can be useful, for instance, if your webhook URL is secured with an API Key. You can add headers to your webhook like this:

{
  "url": "example.com",
  "event": "all",
  "headers": {
    "Authorization": "My API key",
    "X-CLIENT-ID": "Some secret extra information"
  }
}

API Only: Webhook headers currently can only be configured via API, since they may contain sensitive data to be exposed in our dashboard.

For more information see Webhook in our API reference.