Webhooks and Notifications

warning

Webhooks and Notifications are in preview

Webhooks allow you to subscribe to events in PayData. When an events 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 occurres, an HTTP POST will be sent to your endpiont with the payload containing data specific to the type of the event.

Step 3

Test the webhooks using the CreateTestEvent method. 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.

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, provided for the webhook. You can use these headers to ensure that the notification was sent by PayData.

Notification Payload

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

{
  "id": "gdrynkcwy6", 
  "webhookId": "rddzhevagr",
  "eventType": "ReportImported", 
  "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.

Webhooks

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.

Example:

POST /partner/v2/partners/self/webhooks HTTP/1.1
Host: api-sandbox.paydata-api.com
Content-Type: application/json
Authorization: Bearer ********************

{
  "eventTypes": ["ReportImported","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"
}

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`	Array of strings	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"

You get a response similar to the following:

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

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 /partner/v2/partners/self/webhooks/9kmnb73h3w HTTP/1.1
Host: api-sandbox.paydata-api.com
Content-Type: application/json
Authorization: Bearer **************

{
  "eventTypes": ["ReportImported","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
}

PatchWebhook method example:

PATCH /partner/v2/partners/self/webhooks/6kxwh92h3r HTTP/1.1
Host: api-sandbox.paydata-api.com
Content-Type: application/json
Authorization: Bearer *******************************

{
  "headers": 
  {
    "X-Partner-Secret1": "X-Test-Partner-Secret1_new_value",
    "X-Partner-Secret2": "X-Test-Partner-Secret2_new_value"
  },
  "url": "https://example.de/your_new_callback_url"
}

Delete a Webhook

Use the DeleteWebhook method to delete your webhook

DeleteWebhook method example:

DELETE /partner/v2/partners/self/webhooks/6kxwh92h3r HTTP/1.1
Host: api-sandbox.paydata-api.com
Authorization: Bearer **************************

Test and Enable Notifications

You can test your webhooks using the CreateTestEvent method. When you call this endpoint, PayData uses the test event data you provide to create an event as if it were normally created and then sends notifications to the callback URLs specified in the webhooks being tested.

Use the example below and specify your parameters to test the notifications sent to your webhooks

POST /partner/v2/partners/self/test-events HTTP/1.1
Host: api-sandbox.paydata-api.com
Content-Type: application/json
Authorization: Bearer **************

{
  "webHookIds": ["<Tested webhook Id>"],
  "eventType": "<Tested event type code>",
  "eventData": 
  {
    <eventData object is specific to the event type, see descriptions for each event type>
  }
}

In this example

Parameter	Type	Description
`webHookIds`	Array of strings	List of identifiers of the tested webhooks
`eventType`	String	Event type code
`eventData`	Object	Event data object, each event type has its own format, see event types

The tested webhook can have either Active or Disabled status.

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. The URL looks like this: https://webhook.site/#!/view/{unique-id}. It can be used to visualize the incoming notifications. 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 CreateTestEvent method.

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

Overview​

Event Types​

Callback Endpoints​

Notification Headers​

Notification Payload​

Response to Notification​

Webhooks​

Create a Webhook​

Update a Webhook​

Delete a Webhook​

Test and Enable Notifications​

Overview

Event Types

Callback Endpoints

Notification Headers

Notification Payload

Response to Notification

Webhooks

Create a Webhook

Update a Webhook

Delete a Webhook

Test and Enable Notifications