A webhook is an HTTPS URL of yours that receives a POST with a JSON body when an event happens. Two ways to subscribe:
- A Webhook resource —
POST /webhooksAPI with aurland anevent. Delivers that event for every resource of the application. webhookUrlon a resource — set when creating an Item or a Connect Token. Delivers every event, but only for that resource (or the Items created with that token).
Webhook resource#
| Field | Required | Meaning |
|---|---|---|
url | yes | A public HTTPS URL — see URL requirements. localhost is not accepted — use a tunnel such as ngrok while developing. |
event | yes | One event from the tables below, or all for everything. There is no per-product wildcard: to receive every Item event, register all or one webhook per event. |
headers | no | Sent with every delivery to this URL — the way to pass a secret your endpoint verifies. Only configurable through the API, never shown in the dashboard. |
Endpoints: GET /webhooksAPI, POST /webhooksAPI, and retrieve, update and delete on /webhooks/{id}API.
URL requirements#
The url of a webhook — and the webhookUrl of an Item or a Connect Token — must be a public HTTPS endpoint:
| Rule | Rejected example |
|---|---|
| HTTPS only | http://example.com/pluggy |
| Default HTTPS port (443) only | https://example.com:8443/pluggy |
| No username or password in the URL | https://user:pass@example.com/pluggy |
| The host is a domain name, not an IP address | https://203.0.113.10/pluggy |
No localhost or internal names (.local, .internal, .localdomain, .home.arpa) | https://api.internal/pluggy |
| The domain resolves only to public IP addresses | a domain that resolves to 10.0.0.5 |
| At most 2048 characters | — |
Tunnels and request-inspection services such as ngrok or webhook.site are accepted.
A URL that breaks a rule fails with 400, and the message names the rule:
Note
Webhooks registered before a rule existed keep receiving events, but you can't update or re-enable one until its url follows every rule.
Events#
Data
| Event | Fires when |
|---|---|
item/created | An Item was created and connected successfully. |
item/updated | An Item was updated and synced successfully. |
item/deleted | An Item was deleted. |
item/error | An execution ended in error; USER_AUTHORIZATION_PENDING also fires this. |
item/waiting_user_input | The Item needs input from the user (MFA) to continue. |
item/waiting_user_action | The Item needs the user to act on their device — authorise in the bank app, scan a QR code. |
item/login_succeeded | Login at the institution succeeded; data collection is running. |
connector/status_updated | A connector changed status (ONLINE, UNSTABLE, OFFLINE). Carries connectorId. |
transactions/created | New transactions after an update; carries createdTransactionsLink to fetch them. |
transactions/updated | Transactions changed after an update; carries their ids. |
transactions/deleted | Transactions removed after an update; carries their ids. |
Transaction events fire only when something changed; an update with no new transactions emits no transactions/created.
Payments
| Event | Fires when |
|---|---|
payment_intent/created | A payment intent was created for a request. |
payment_intent/waiting_payer_authorization | The intent needs the payer's authorisation. |
payment_intent/completed | The intent completed. |
payment_intent/error | The intent failed. |
payment_request/updated | A payment request changed status. |
scheduled_payment/created, /completed, /error, /canceled | One scheduled payment of an authorisation moved. |
scheduled_payment/all_created, /all_completed | Every scheduled payment of an authorisation was created / completed. |
automatic_pix_payment/created, /completed, /error, /canceled | A payment of an Automatic PIX request moved. |
smart_transfer_preauthorization/completed, /error | A Smart Transfer pre-authorisation was approved, or failed. |
smart_transfer_payment/completed, /error | A Smart Transfer payment settled, or failed. |
Payload#
Every notification carries:
| Field | Meaning |
|---|---|
event | The event name. |
eventId | Identifies the event; the same value when one event is delivered to several URLs. |
clientId | The Client ID of the application the webhook belongs to. Ignore a notification whose clientId isn't yours. |
triggeredBy | USER (a Connect Token, e.g. the widget), CLIENT (an API Key, e.g. a PATCH), SYNC (auto-sync) or INTERNAL (Pluggy support). Absent on item/deleted, connector/status_updated and transactions/deleted. |
| the entity's id | itemId on Item events, transactionIds on transaction events, connectorId on connector events, and so on per event. |
clientUserId | On item/* events only — the value set through the Connect Token's options. Not on transactions/*: map those to your user through itemId. |
Delivery and retries#
A delivery succeeds when your endpoint answers 2xx within 10 seconds. Respond first, process afterwards — a slow handler is counted as a failure and retried.
On failure: up to 3 attempts in total — immediately, ~15 minutes after the first fails, then ~2 hours after the second. After that the event is discarded. Statuses 400, 401, 403, 404 and 405 are never retried. Exception: item/login_succeeded and item/waiting_user_input get their 3 attempts ~6 minutes apart, never the 2-hour wait.
Redirects are not followed: a 3xx counts as a failure. If the domain resolves to a private or reserved IP address when the notification is sent, it is not delivered and not retried.
Read the guide: Webhook — payload examples per event, and troubleshooting.
