Webhooks and Notifications

warning

Webhooks and Notifications are in preview

Webhooks allow you to subscribe to events in PayData. When an event occurs, PayData sends an HTTP POST notification to the callback URL configured for the webhook. This enables real-time event-based interaction of your system with PayData and saves you the effort to repeatedly poll PayData API to get the necessary data.

Overview

To receive and process notifications from PayData follow these steps:

Step 1

Familiarize yourself with the event types, supported by PayData.

Create one or more endpoints on your web server that will accept HTTP POST requests from PayData. Consider creating one public endpoint for all event types you want to receive notifications about. The handler for the endpoint could get the event type information from the notification header and then route the notification to another handler according to the type of the event.

Step 2

Create one or more PayData webhooks for the partner using the CreateWebhook method. Consider setting up one webhook per endpoint created in step 1. You specify the URL of your endpoint as the url parameter of the webhook. Provide a list of event types supported by your endpoint in the eventTypes parameter. Each time an event of any of these types occurs, an HTTP POST will be sent to your endpoint with the payload containing data specific to the type of the event.

Step 3

Test the webhooks using the test-event endpoints. Enable the webhooks and start receiving notifications.

Details for these steps are provided below.

Event Types

PayData currently supports these event types:

TransactionsImported - transactions for a certain period of time with or without a report have been successfully received from a payment provider and imported or if an error occured while importing the transactions.
AccountCreated, AccountUpdated or AccountDeleted - an account has been created, updated or deleted.
AccountTypeUpdated - an account type has been updated. This notification provides information on payment provider problems.

Each PayData event type has its own payload model.

Prefer notifications over polling

AccountUpdated and TransactionsImported fire once new data is actually ready, but how long that takes after account creation is not predictable — see the timing note in Staying Up to Date. Subscribing to these events avoids having to guess a polling interval.

Callback Endpoints

After you chose the event types you want to be notified about, create an endpoint that accepts HTTP POST requests. Information about the event is sent by PayData in request headers and body.

Notification Headers

X-PayData-Notification-Id - a unique identifier of the notification
X-PayData-Webhook-Id - a unique identifier of the webhook
X-PayData-Event-Type - the type of the event

The identifier can be used by PayData Support to deal with possible issues. Additionally, you can use it to avoid processing the same notification more than once, although PayData ensures that a successfully sent notification is not sent again.

The event type can be used to route the request to the appropriate handler in your system.

Additionally PayData sends the partner headers you configured for the webhook (the headers parameter of CreateWebhook, for example X-Partner-Secret1 in the example below). You can use these headers to ensure that the notification was sent by PayData.

note

PayData does not currently sign notifications with a cryptographic signature (e.g. HMAC) — the partner headers are the only verification mechanism. Treat their values as shared secrets: keep them out of logs and client-side code, and consider rotating them periodically.

Notification Payload

The notification body or payload is in JSON format and contains the event details.

{
  "id": "gdrynkcwy6",
  "webhookId": "rddzhevagr",
  "eventType": "TransactionsImported",
  "eventRaisedAt": "2024-06-21T09:31:35.6920617Z",
  "eventData": {...}
}

In this example

Parameter	Type	Description
`id`	String	Notification id, same as in `X-PayData-Notification-Id` header
`webhookId`	String	Webhook id, same as in `X-PayData-Webhook-Id` header
`eventType`	String	Event type code, same as in `X-PayData-Event-Type` header
`eventRaisedAt`	DateTime	event raised timestamp
`eventData`	Object	Event data object, each event type has its own format, see event types

Response to Notification

Your endpoint should return a 200 OK HTTP response to the notification, if it is successfully delivered. Respond as quickly as possible after you receive the notification, do not wait until it is processed.

Retry Behavior

If your endpoint does not return a 200 OK, PayData retries delivery:

For transient errors (e.g. a connection or request timeout), delivery is retried immediately, up to 3 times, with a 5 second timeout per attempt.
If delivery is still unsuccessful, it is treated as an unexpected error: the next retry happens after 5 minutes, followed by up to 9 further retries.

Make sure your endpoint responds quickly and reliably — repeated failures delay delivery of the notification and consume retry attempts.

Webhooks

Base URL differs from the rest of the API

Webhook management lives under a separate base path, /webhook/v1, not under /partner/v2 like the rest of this documentation. The host is the same as your environment's main API host (sandbox.paydata-api.com or api.paydata-api.com), only the path prefix changes:

https://sandbox.paydata-api.com/webhook/v1/webhooks

It still accepts the same partner token and scopes (webhook:all / webhook:read / etc.), it's only the path that's different.

Create a Webhook

Use the CreateWebhook method to create your webhook. Consider creating your webhooks as disabled (status = Disabled), testing and then enabling (status = Active) them.

POST /webhooks

CreateWebhook

POST /webhook/v1/webhooks HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}
Content-Type: application/json

Request Body

{
  "eventTypes": [
    "TransactionsImported",
    "AccountCreated"
  ],
  "url": "https://example.de/callback_url",
  "headers": {
    "X-Partner-Secret1": "X-Test-Partner-Secret1",
    "X-Partner-Secret2": "X-Test-Partner-Secret2"
  },
  "sslVerificationDisabled": true,
  "status": "Disabled"
}

Response — HTTP/1.1 201

{
  "id": "rzmzhmjt14",
  "eventTypes": [
    "TransactionsImported",
    "AccountCreated"
  ],
  "url": "https://example.de/callback_url",
  "headers": {
    "X-Partner-Secret1": "X-Test-Partner-Secret1",
    "X-Partner-Secret2": "X-Test-Partner-Secret2"
  },
  "sslVerificationDisabled": true,
  "createdAt": "2024-06-14T07:40:16.3987696Z",
  "lastModifiedAt": "2024-06-20T09:47:46.6557667Z",
  "status": "Disabled"
}

In this example

Parameter	Type	Description
`eventTypes`	Array of strings	List of event types you subscribe to
`url`	String	Your callback URL, PayData will send notifications to
`headers`	Object	Partner headers, use them to check that the notifications come from PayData
`sslVerificationDisabled`	Boolean	If true, the server certificate validation is disabled
`status`	String	"Active" or "Disabled"

List and Get Webhooks

Use GetWebhooks to list all webhooks for the partner, or GetWebhook for a single one.

GET /webhooks

GetWebhooks

GET /webhook/v1/webhooks HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}

Response — HTTP/1.1 200

{
  "webhooks": [
    {
      "id": "rzmzhmjt14",
      "eventTypes": [
        "AccountCreated"
      ],
      "url": "https://example.de/callback_url",
      "headers": {},
      "sslVerificationDisabled": false,
      "createdAt": "2026-09-07T20:38:24.0329064Z",
      "lastModifiedAt": "2026-09-07T20:39:10.5389239Z",
      "status": "Active"
    }
  ]
}

Update a Webhook

To change your webhook settings you can use these methods:

UpdateWebhook method requires that you specify all webhook properties and updates them all
PatchWebhook method allows you to change individual properties, for example, status or URL, and leave other properties unchanged

UpdateWebhook method example:

PUT /webhooks/rzmzhmjt14

UpdateWebhook

PUT /webhook/v1/webhooks/rzmzhmjt14 HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}
Content-Type: application/json

Request Body

{
  "eventTypes": [
    "TransactionsImported",
    "AccountCreated"
  ],
  "url": "https://example.de/your_new_callback_url",
  "headers": {
    "X-Partner-Secret1": "X-Test-Partner-Secret1_new_value",
    "X-Partner-Secret2": "X-Test-Partner-Secret2_new_value"
  },
  "status": "Active",
  "sslVerificationDisabled": false
}

Response — HTTP/1.1 200

{
  "id": "rzmzhmjt14",
  "eventTypes": [
    "TransactionsImported",
    "AccountCreated"
  ],
  "url": "https://example.de/your_new_callback_url",
  "headers": {
    "X-Partner-Secret1": "X-Test-Partner-Secret1_new_value",
    "X-Partner-Secret2": "X-Test-Partner-Secret2_new_value"
  },
  "sslVerificationDisabled": false,
  "createdAt": "2024-06-14T07:40:16.3987696Z",
  "lastModifiedAt": "2024-06-20T09:47:46.6557667Z",
  "status": "Active"
}

PatchWebhook method example:

PATCH /webhooks/rzmzhmjt14

PatchWebhook

PATCH /webhook/v1/webhooks/rzmzhmjt14 HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}
Content-Type: application/json

Request Body

{
  "status": "Active"
}

Response — HTTP/1.1 200

{
  "id": "rzmzhmjt14",
  "eventTypes": [
    "TransactionsImported",
    "AccountCreated"
  ],
  "url": "https://example.de/callback_url",
  "headers": {
    "X-Partner-Secret1": "X-Test-Partner-Secret1",
    "X-Partner-Secret2": "X-Test-Partner-Secret2"
  },
  "sslVerificationDisabled": true,
  "createdAt": "2024-06-14T07:40:16.3987696Z",
  "lastModifiedAt": "2024-06-20T09:47:46.6557667Z",
  "status": "Active"
}

Delete a Webhook

Use the DeleteWebhook method to delete your webhook.

DELETE /webhooks/rzmzhmjt14

DeleteWebhook

DELETE /webhook/v1/webhooks/rzmzhmjt14 HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}

Response — HTTP/1.1 204

Test and Enable Notifications

One endpoint per event type

There is no single, generic "create test event" endpoint that takes an arbitrary eventType field. Instead there is one test endpoint per event type, and the request body shape is specific to that event type:

POST /webhook/v1/testevents/accountcreated — body: { "account": {...}, "webhookIds": [...] }
POST /webhook/v1/testevents/accountupdated — same shape as above
POST /webhook/v1/testevents/accountdeleted — same shape as above
POST /webhook/v1/testevents/accounttypeupdated
POST /webhook/v1/testevents/transactionsimported

If webhookIds is omitted or empty, the test notification is sent to all active webhooks subscribed to that event type.

Use the example below (for AccountCreated) and specify your parameters to test the notifications sent to your webhooks. account.id must be a real, existing account id for your partner — an arbitrary string is rejected with 400 Bad Request: Invalid account ID.

POST /webhook/v1/testevents/accountcreated HTTP/1.1
Host: sandbox.paydata-api.com
Content-Type: application/json
Authorization: Bearer **************

{
  "account": {
    "id": "<an existing account id>",
    "name": "Test Account",
    "status": "Idle"
  },
  "webhookIds": ["<Tested webhook Id>"]
}

The tested webhook can have either Active or Disabled status — testing against a Disabled webhook lets you verify the payload without risking a real delivery to a handler that isn't ready yet.

Each test-event call's own response contains the list of notifications it actually sent, using the same payload shape documented for that event type — useful for inspecting the exact payload without needing a publicly reachable callback URL yet.

tip

It could be useful to create test events before or while you develop your handlers to get real examples of the notification payload. To do so you can use such tools as https://webhook.site which creates a unique callback URL for you. Set up the url property of your webhook created in step 2 to that URL, then you can see the notifications you create with the test-event endpoints above show up there in real time.

After you test the webhook, use the UpdateWebhook method or the PatchWebhook method to change the status to Active and start receiving PayData notifications.

note

Use the event types listed above (TransactionsImported, AccountCreated, AccountUpdated, AccountDeleted, AccountTypeUpdated) when creating a webhook. Some API reference material also mentions TransactionsImportError and AccountError; these are not currently usable values — subscribe to the types listed above instead.

Overview​

Event Types​

Callback Endpoints​

Notification Headers​

Notification Payload​

Response to Notification​

Retry Behavior​

Webhooks​

Create a Webhook​

List and Get Webhooks​

Update a Webhook​

Delete a Webhook​

Test and Enable Notifications​

Overview

Event Types

Callback Endpoints

Notification Headers

Notification Payload

Response to Notification

Retry Behavior

Webhooks

Create a Webhook

List and Get Webhooks

Update a Webhook

Delete a Webhook

Test and Enable Notifications