Webhooks Destination

1. From the Segment web app, click Catalog.
2. Search for "Webhooks" in the Catalog, select it, and choose which of your sources to connect the destination to.
3. Specify up to five different Webhook URLs that you'd like to forward data to.
4. Add any header values you'd like to add to the HTTP requests.
5. If you require authentication, add a shared secret.
6. Enable the destination to send data to the configured webhook.

When Segment sends an event to a webhook endpoint, the service must respond within 5 seconds. If Segment doesn't receive a response within that period, the system logs a timeout error and retries the event later.

If you're not familiar with the Segment Specs, take a look to understand what the Page method does. An example call would look like:

POST https://your-webhook-url.com/x

1
User-Agent: Segment.io/1.0
2
Content-Type: application/json

1
{
2
    "version"       : 1,
3
    "type"          : "page",
4
    "userId"        : "019mr8mf4r",
5
    "properties"    : {
6
        "path"      : "/pricing",
7
        "referrer"  : "https://segment.com",
8
        "title"     : "Segment Pricing",
9
        "url"       : "https://segment.com/pricing"
10
    },
11
    "timestamp" : "2012-12-02T00:30:08.276Z"
12
}

If you're not familiar with the Segment Specs, take a look to understand what the Screen method does. An example call would look like:

POST https://your-webhook-url.com/x

1
User-Agent: Segment.io/1.0
2
Content-Type: application/json

1
{
2
    "version"   : 1,
3
    "type"      : "screen",
4
    "userId"    : "019mr8mf4r",
5
    "name"      : "Main Screen",
6
    "timestamp" : "2012-12-02T00:30:08.276Z",
7
    "context"   : {
8
        "device"     : {
9
            "model"  : "x86_64",
10
            "type"   : "ios"
11
        },
12
        "os"         : {
13
            "name"   : "iPhone OS",
14
            "version": "7.1"
15
        },
16
        "app"        : {
17
            "build"  : "88",
18
            "name"   : "YourApp",
19
            "version": "2.0.0"
20
        }
21
    }
22
}

If you're not familiar with the Segment Specs, take a look to understand what the Identify method does. An example call would look like:

POST https://your-webhook-url.com/x

1
User-Agent: Segment.io/1.0
2
Content-Type: application/json

1
{
2
    "version"   : 1,
3
    "type"      : "identify",
4
    "userId"    : "019mr8mf4r",
5
    "traits"    : {
6
        "email"            : "achilles@segment.com",
7
        "name"             : "Achilles",
8
        "subscriptionPlan" : "Premium",
9
        "friendCount"      : 29
10
    },
11
    "timestamp" : "2012-12-02T00:30:08.276Z"
12
}

If you're not familiar with the Segment Specs, take a look to understand what the Track method does. An example call would look like:

POST https://your-webhook-url.com/x

1
User-Agent: Segment.io/1.0
2
Content-Type: application/json

1
{
2
    "version"    : 1,
3
    "type"       : "track",
4
    "userId"     : "019mr8mf4r",
5
    "event"      : "Purchased an Item",
6
    "properties" : {
7
        "revenue"        : "39.95",
8
        "shippingMethod" : "2-day"
9
    },
10
    "timestamp" : "2012-12-02T00:30:08.276Z"
11
}

If you're not familiar with the Segment Specs, take a look to understand what the Alias method does. An example call would look like:

POST https://your-webhook-url.com/x

1
User-Agent: Segment.io/1.0
2
Content-Type: application/json

1
{
2
    "version"   : 1,
3
    "type"      : "alias",
4
    "Previous ID"      : "previousId",
5
    "User ID"        : "userId",
6
    "timestamp" : "2012-12-02T00:30:08.276Z"
7
}

If you're not familiar with the Segment Specs, take a look to understand what the Group method does. An example call would look like:

POST https://your-webhook-url.com/x

1
User-Agent: Segment.io/1.0
2
Content-Type: application/json

1
{
2
    "version"   : 1,
3
    "type"      : "group",
4
    "groupId"   : "0e8c78ea9d97a7b8185e8632",
5
    "userId"    : "019mr8mf4r",
6
    "traits"    : {
7
        "name"             : "Initech",
8
        "industry"         : "Technology",
9
        "employees"        : 329,
10
        "plan"             : "Enterprise",
11
        "total billed"     : 830
12
    },
13
    "timestamp" : "2012-12-02T00:30:08.276Z"
14
}

When you create a deletion request, for each affected source that has webhooks enabled, Segment forwards a notification so that you can start any automations needed. An example call would look like:

POST https://your-webhook-url.com/x

1
User-Agent: Segment.io/1.0
2
Content-Type: application/json

1
{
2
    "type"      : "delete",
3
    "userId"    : "019mr8mf4r",
4
    "timestamp" : "2012-12-02T00:30:08.276Z"
5
}

If you want to authenticate the requests being sent to your webhook endpoint, you can add a sharedSecret to the advanced option settings. If you provide this, Segment signs your requests using the shared secret and the body of the request, and add that as the ​X-Signature​ header. Segment calculates a SHA1 digest using the shared secret and the JSON-stringified body of the request.

An example of how one might authenticate the requests would be:

1
 var signature = req.headers['x-signature'];
2
 var digest = crypto
3
     .createHmac('sha1', settings.sharedSecret)
4
     .update(new Buffer(JSON.stringify(req.body),'utf-8'))
5
     .digest('hex');
6

7
if (signature === digest) {
8

9
 // do cool stuff
10

11
}

For Batch events, the process to authenticate these requests slightly differs as it involves verifying the X-Signature header against a hash of the first event in the batch.

An example of how you might authenticate batch requests would be:

1
 const signature = req.headers['x-signature'];
2
 const digest = crypto
3
       .createHmac('sha1', 'sharedsecretvalue')
4
       .update(JSON.stringify(req.body[0]),'utf-8')
5
       .digest('hex');
6

7
if (signature === digest) {
8

9
 // do cool stuff
10

11
}

If your server is using HTTPS, note that our webhooks destination does not work with self-signed certs. If webhooks detects a self-signed cert it will throw an error and no request will be sent.

Under 'Connection Settings', you can provide up to 5 webhooks.

If sending a message to any of the webhooks succeeds, the message is considered successfully processed and request to the other webhooks won't be retried. If your webhooks aren't robust, consider using the Iron.io destination.

Segment retries requests that fail due to temporary errors, like timeouts and 5xx status codes, for up to four hours.

You can send computed traits and audiences generated using Engage to this destination as a user property. To learn more about Engage, schedule a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to false.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

Segment lets you change these destination settings from the Segment app without having to touch any code.