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 let you subscribe to events generated by CDS Global. When a subscribed event occurs, a request will be sent to the configured endpoint.

You can use webhooks to keep your environment in sync with CDS Global's system. For example, when a customer cancels a subscription, a subscription.cancelled webhook event can be sent. 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.
type	Name of the webhook event (ie subscription.cancelled).
source	URI of the souce of the webhook event (ie. https://api.cdsglobal.co.uk).
id	Unique identifier of the webhook event.
time	Timestamp of when the webhook event was raised.
datacontenttype	Content type of the webhook payload (application/json).
data	The webhook event data. See webhook events for available data points.

JSON

{
    "specversion" : "1.0",
    "type" : "subscription.created",
    "source" : "https://api.cdsglobal.co.uk",
    "id" : "A234-1234-1234",
    "time" : "2026-04-05T17:31:00Z",
    "datacontenttype" : "application/json",
    "data" : webhook payload
}

IMPORTANT

Webhooks may not be received in chronological order. While webhooks are generated 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, confirming that you have successfully received the webhook event.

If your endpoint doesn't respond within 5 seconds, this will be considered a failed delivery and the request will be attempted again. Additionally, the request will be attempted again if the endpoint responds with a HTTP status code of 500 or higher.

Each request will be attempted 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.