10

Webhook Destination

About this integration

Webhooks submit real-time user data to your own HTTP endpoints. A Webhook is an HTTP callback: a simple HTTP POST event to any URL you want when something happens—like when data comes in from a source.

Getting started

Our webhook destination lets you transform and send data to any URL you maintain. It’s basically a custom destination, letting you handle source data however you want.

1. Go to the Data Pipelines tab and click Connections.

2. Click Add New under Destinations.

3. Select the Webhooks destination.

4. (Optional) Select the sources that you want to connect to this destination. You can always connect sources to your destination later. We’ll only show you eligible sources.

5. Configure your destination.

   1. Shared Secret: If set, request will be signed with an HMAC in the "X-Signature" request header. The HMAC is a hex-encoded SHA1 hash generated using this shared secret and the request body.

6. Click Enable Destination.

Securing webhook requests

We recommend that you use a Shared Secret to secure your webhook URL and ensure that you only ingest requests that come from Data Pipelines. When you use a shared secret, we’ll sign requests with an X-Signature header containing a hex-encoded SHA1 hash from the shared secret and request body. You can use this signature to verify that the request came from Customer.io.

Actions

A webhook request has one action: Send. This action lets you map incoming data to a URL you maintain.

When you set up a webhook Send action, you’ll set:

1. The Trigger for the action: typically this is the type of incoming data (identify, track, etc). But you may also want to send specific events like email_opened or product_viewed.
2. The URL to send the data to.
3. The HTTP method to use: POST, PUT, PATCH, or DELETE.
4. Whether or not to batch events: We batch up to 1000 events matching the trigger in a single request. See Batching for more information.
5. Set your HTTPS Headers and the data you want to send in the payload. Like most actions, we typically recommend that you send the userId, event name, and properties or traits from the incoming call, but you may want to set up specific mappings.

Batching

If you want to send fewer calls to your webhook endpoint, you can batch your webhook requests in groups of up 1000 events.

Batched objects have a top-level batch key: an array containing the bodies of incoming requests that match your trigger criteria. For example, if your trigger is based on track events, the batch key contains an array of objects matching the Data.

Given the data below for track events, we expect a batch to look a bit like this.

{
  "batch": [
    {
      "type": "track",
      "userId": "123",
      "event": "Signed Up",
      "properties": {
        "plan": "Startup",
        "referred_by": "Friend"
      }
    },
    {
      "type": "track",
      "userId": "456",
      "event": "Signed Up",
      "properties": {
        "plan": "Free",
        "referred_by": "Ad"
      }
    }
  ]
}