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 to 1000 events. We send each batch as an array of objects where each object is the body of an incoming request that matches your trigger criteria.

For example, imagine that you’ve mapped track events as shown in the image below. The code sample below the image is an example of what we’d send to your webhook endpoint.

[
  {
    "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"
    }
  }
]