Webhooks and Event Notifications

The CSP API offers webhook events grouped into several categories. You can subscribe to these webhooks to receive a notification of events by category type. A subscription is created by associating a CSP webhook endpoint to a specified event category (see the example below). The webhook event itself is a flat-map JSON data structure that contains an eventType property (along with others) that provide important information.

Please be aware that new properties may be added in future releases. To ensure forward compatibility, you should make sure that webhook endpoints are capable of handling unexpected properties.

Webhook Example

Notification of campaign suspension by AT&T:

POST / HTTP/1.1
Host: tcr.requestcatcher.com
Accept: *.*
Connection: keep-alive
Content-Length: 226
Content-Type: application/json; utf-8
X-Registry-Signature: SmqzLvP6uQDM6DD2lfdLqwiJJbo=
{
  "cspId" : "S123ABC",  "brandName" : "Microsoft",  "mnoName" : "AT&T",
  "campaignId" : "C123ABC",  "campaignReferenceId" : "C-XXXXX",  "brandId" : "B123ABC",
  "brandReferenceId" : "Q-XXXXXXXX",  "mnoId" : 10017,
  "eventType" : "MNO_CAMPAIGN_OPERATION_SUSPENDED",
  "cspName" : "ACME"
}

Webhook Delivery

Delivery Order

The CSP API delivers webhook events in chronological order. For example, a campaign registration might generate the following events for a CSP:

• CAMPAIGN_ADD: A campaign was registered.

• CAMPAIGN_SHARE_ACCEPT/CAMPAIGN_SHARE_DELETE: An upstream CNP accepted a campaign.

• CAMPAIGN_DCA_COMPLETE: A campaign was accepted by all DCAs to which it was submitted.

The order of event delivery is exactly the same as the order in which the events were generated. In order to support this First In, First Out (FIFO) requirement, events are funneled through account-specific queues for delivery. There is only one active delivery worker per account/queue. While the delivery order is guaranteed, duplicate events are possible if there are network or system disruptions.

Webhook Retry Policy

The CSP API tries to ensure that each webhook event is accepted by a CSP’s registered webhook endpoint. If a webhook endpoint times out or errors out (e.g., an HTTP 400 response), The CSP API will attempt to retry delivery based on a set schedule (as shown below).

The CSP API will not move to the next event in the queue until the current pending event is accepted by a CSP’s endpoint, or if it is discarded following several retry attempts. Webhook endpoint should not be designed to reject webhook events that aren’t needed or recognized. Doing so will trigger additional retry attempts on failed events and prevent the timely delivery of other events in the queue.

Exponential Back-Off Retry Schedule

After 13 failed retry attempts, the event is discarded. Currently, there are no methods for recovering these lost events.

Webhook Authentication

To ensure secure communication between the CSP API and subscriber applications, all webhook notifications will have an HMAC-SHA1 signed X-Registry-Signature authentication header. To verify the signed signature, follow these steps:

1. Canonicalize the JSON raw content (webhook notification body) into a string. If needed, refer to the JCS defined canonicalization scheme.

2. Build the string to be signed as stringToSign = {webhook URL + canonicalized string}.

3. Set AuthKey = {subscriber's SECRET key}.

4. Apply the HMAC-SHA1 algorithm on the stringToSign with authKey and get the signedString. For more information, refer to the section “How to Validate a Webhook Signature using HMAC” in the Webhook Instructions for CSP API document.

5. Compare the X-Registry-Signature value with the signedString to determine the authenticity of the webhook notification.

Webhook IP Addresses

When creating webhooks for CSP applications, the CSP API uses the following IP addresses per development environment:

Disaster Recovery IP addresses are servers in a different physical location than the primary data center, and are used in case the primary data center is rendered unusable.