Webhook

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 in 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.

Currently, we support registering for the following events:

To register for a specific event you will have to send the desired one as the event to attach. Alternatively, you can just use the option all to receive all events associated.

We only accept HTTPS URLs. Localhost URL are not allowed to be used, you will have to provide an HTTPS URL using ngrok or other tools to provide public secured 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 is sent to many endpoints.
• clientId: client 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:

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

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

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

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

{
  "event": "item/waiting_user_input",
  "eventId":"d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
  "triggeredBy": "USER"
}

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

Connector examples:

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

Transaction examples

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

Payment Intent examples

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

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

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

Schedule Payments examples

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

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

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

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

Handling notifications

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

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

When there is a failure, we retry the notification up to 3 times, with one minute in between retries. After that, the notification will be lost.

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, it's doing 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:

177.71.238.212

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

📘

For more information see Webhook in our API reference.

View, create and edit webhooks from Dashboard.

You can also manage your application's webhooks from Dashboard.

1. Enter into dashboard.pluggy.ai
2. Go to the "Applications" tab
3. Enter the application settings page by clicking the pencil icon in the application where you want to manage webhooks.

Here you'll be able to see the webhooks you already created, edit the URL and events that it's subscribed, delete it or even disable it.

📘

Note

Only team admins or owners can edit webhooks.