Partner Callbacks allow your system to receive real-time notifications when specific events occur within our platform. Instead of polling our API for updates, we push the data directly to your server as soon as it's available.
Part 1: Understanding Callbacks
Webhook Registration
To start receiving notifications, you must register a Callback URL. This endpoint must be a publicly accessible HTTPS URL hosted by you, capable of receiving POST requests from our servers. You can manage these URLs dynamically using our Callback API.
Key Features
- Real-time Updates: Get notified immediately as events happen on our platform.
- Retry Logic: Our system automatically retries delivery if your server is temporarily offline or fails to respond successfully.
- Programmatic Management: Create, list, and delete your webhook subscriptions on the fly via our API.
Managing Your Callbacks
You can programmatically manage your webhook subscriptions using the endpoints detailed below. For a complete technical breakdown and to test these endpoints directly, please refer to our API Reference Documentation.
1. Create or Update a Callback
PUT /{partnerUniqueID}/callbacks/{notificationType} View API Reference
Use this endpoint to configure a new webhook destination or update an existing one for a specific event type. Validation ensures that the partner exists and that the requested notification type is supported.
2. List Configured Callbacks
GET /{partnerUniqueID}/callbacks View API Reference
Retrieves a list of all your currently active webhook subscriptions and their details. This is useful for auditing your active integrations.
3. Delete a Callback
DELETE /{partnerUniqueID}/callbacks/{notificationType} View API Reference
Removes an existing webhook subscription for a specific notification type. Once deleted, you will no longer receive pushes for that event type until you register a new URL. Note: This will return a 404 Not Found if the configuration does not exist.
Part 2: Testing Your Integration
Before going live, we highly recommend validating your webhook receiver. We provide a dedicated Test Endpoint (Echo) that allows you to trigger a simulated event. Calling this API instructs our system to fire a test webhook to your registered Callback URL, allowing you to verify your firewall settings and payload parsing logic.
Trigger a Test Notification
To trigger a test, make a POST request to the following endpoint:
POST /v1/callbacks/echo/{partnerUniqueID}/{notificationTypeID}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
partnerUniqueID | GUID | Your unique partner identifier. |
notificationTypeID | integer | The ID of the event type you want to simulate (5, 6, or 7). |
Request Body (rawBody)
When calling the test endpoint, the rawBody you provide will dictate the payload we send to your webhook. The structure required changes based on the notificationTypeID. You can follow this link to see the expected payload formats for each notification type:
View API Reference
🛑 Important Logic Rule: You must provide either
processUniqueIdorsimulationUniqueId.
- Providing both will return a 400 Bad Request.
- Providing neither will return a 400 Bad Request.