Webhooks¶

Webhooks are a mechanism that allows your backend to receive events from Consumer Intelligence as they occur.

Integrate with webhooks so your application can receive updates about your consumers and subscriptions in near-real time, without having to constantly query our API.

To enable webhook events, you need to register webhook endpoints. After you register them, Consumer Intelligence can push near real-time events to your application's webhook endpoint when events happen to your entities in Consumer Intelligence. Consumer Intelligence uses HTTPS to send webhook events to your endpoint as a JSON payload.

Receiving webhook events is particularly useful to for listening on asynchronous events that can be used for triggered-based marketing campaigns, such as life events or changes to enrichment variables.

Get started¶

To start receiving webhook events, create and register a webhook endpoint using the Create webhook endpoint.

After registering a new webhook, a test event will be sent your endpoint. If you want to make changes to your webhook, you first need to create a new webhook, then use the Delete webhook endpoint to delete the old webhook.

Implementing your webhook endpoint¶

Your webhook endpoint should expect to receive POST requests bearing the following case-insensitive headers:

Header	Description
`ci-signature-timestamp`	Timestamp in seconds since epoch UTC of the delivery.
`ci-signature-sha256`	Signature authenticating that Consumer Intelligence is the author of the delivery.

And an application/json body containing an array of events, with the following schema:

{
  "id": "string",
  "type": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

Each event object may contain additional properties, depending on the event.

Security¶

There are several methods you can use to ensure the security of the communication between Consumer Intelligence and your servers.

Verifying a payload signature¶

Requests to your endpoint will bear a ci-signature-sha256 signature header verifying that the request has come from us.

The signature is the HMAC hex digest of the payload, where:

algorithm = sha256
key = your secret returned on webhook creation
payload = delivery timestamp (from the ci-signature-timestamp header) and the request body (a UTF-8 encoded string containing JSON) separated by dot (.)

A delivery of {"payload":"example"} signed with example-secret and a ci-signature-timestamp of 1234567890 would have an ci-signature-sha256 of 316940504080917f1b137a5fc9974589e724c6254b59e8d6c9f661b8a605d808.

In Javascript, the signature may be verified as follows:

// node.js + express example

// read signature from request HTTP header
const ciSignatureTimestamp = Buffer.from(req.get("ci-signature-timestamp"), "utf8");
const ciSignatureSha256 = Buffer.from(req.get("ci-signature-sha256"), "utf8");

// compute signature using your secret, signature timestamp and the request payload
const payload = ciSignature + "." + req.body;
const hmac = crypto.createHmac("sha256", "<your secret>");
const digest = Buffer.from(hmac.update(payload).digest("hex"), "utf-8");

// check whether they match, using timing-safe equality (don't use ==)
if (!crypto.timingSafeEqual(digest, ciSignatureSha256)) {
    throw new Error("Invalid signature");
}

Validating the timestamp¶

To prevent replay attacks from a malicious third party, you can use ci-signature-timestamp to reject deliveries older than a couple of seconds. We will always create new timestamps on new deliveries (even rejected). You should keep this greater than the 5-second timeout on deliveries from our end.

IP addresses¶

As an additional security measure you can also verify that webhook deliveries originate from a Consumer Intelligence IP address.

Requests made by us are made from the IP addresses specified below.

IP
18.195.53.191
18.184.182.182

For API products where we make requests to your servers, please make sure that these request servers are allowed through firewalls, etc.

Timeouts, failures and unhealthy webhooks¶

Webhook deliveries time out after 5 seconds. If we notice 100 consecutive delivery failures to your webhook, either due to timeout or failing to receive a 2xx response from you, we will mark your webhook as unhealthy. Any new deliveries will be immediately marked as failed, and retried according to normal flow. After a failed delivery, we will attempt to redeliver your events daily for 14 days. If any of the retry attempts succeeds, the webhook will be considered healthy again. But if all retry attempts fail, all pending events will be deleted.

Best practices¶

Respond within 5 seconds¶

Your server should respond with a 2xx response within 5 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then Consumer Intelligence terminates the connection and considers the delivery a failure.

In order to respond in a timely manner, you may want to set up a queue to process webhook payloads asynchronously. Your server can respond when it receives the delivery, and then process the payload in the background without blocking future webhook deliveries.

Only listen to event types your integration requires¶

Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server, and we don't recommend it.

You can change the events that a webhook endpoint receives only when you create a webhook.

Supported events¶

You can find the list of supported events in the Webhook events section of the API reference.