Appearance
Handle webhook delivery
Once a webhook endpoint is configured for an event, you should handle the webhook delivery to make sure the integration performs well.
How it works
Webhooks lets you subscribe to events in xChange. When a subscribed event occurs, xChange sends a request to the configured endpoint.
You can use webhooks to keep your system in sync with xChange. For example, when a customer cancels a subscription, xChange can send you a subscription.cancelled webhook event. When you receive this, your system can handle it and restrict customer access to digital content.
What does a Webhook look like?
It looks like a standard HTTP POST request.
Details regarding the event are embedded as a JSON object. Additionally, a webhook signature header is included in the request which will help verifying the integrity of the payload.
Webhook payload follows the CloudEvents specification schema and it includes the following information:
| Attribute | Description |
|---|---|
| specversion | Version of CloudEvents specification. |
| id | Unique identifier of the webhook event. |
| type | Name of the webhook event (ie subscription.cancelled). |
| time | Timestamp of when the webhook event was raised. |
| source | URI of the souce of the webhook event (ie. https://api.cdsglobal.co.uk). |
| datacontenttype | Content type of the webhook payload (application/json). |
| data | The webhook event data. See webhook events for available data points for each webhook. |
IMPORTANT
Webhooks may not be received in chronological order. While xChange sends webhooks chronologically, there is no guarantee your servers receives them in the same order. Compare the time value against your locally stored value to know which is most recent.
Respond to events
Your endpoint should respond with a 200 HTTP status code within 5 seconds. This lets xChange know that you have received the webhook event succesfully.
If your endpoint doesn't respond within 5 seconds, xChange will consider the delivery as failed and will attempt to send the request again. Additionally, xChange will attempt to send the request again if the endpoint responds with a HTTP status code of 500 or higher.
xChange will attempt to send the request using an exponential backoff retry with a maximum of 10 attempts within a 24 hour period. After the retry attempts are exhausted or the timeout period (24 hours) is reached, the webhook event will be dropped and an incident notification will be sent to CDS.