Webhooks Destination

Segment Webhooks submit real-time user data to your own HTTP endpoints. A Webhook is an HTTP callback: a simple event-notification using HTTP POST. A web application implementing Webhooks will POST a message to a URL when certain things happen.

This document was last updated on January 28, 2018. If you notice any gaps, out-dated information or simply want to leave some feedback to help us improve our documentation, let us know!

Getting Started

Before you start, make sure Webhooks supports the source type and connection mode you’ve chosen to implement. You can learn more about connection modes here.

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, you would like to forward data to.
4. Add in any header values you would like to add to the HTTP requests
5. If you require authentication, add in a shared secret.
6. Toggle on Webhooks and we will start sending all the requests received by Segment’s API.

Note: We’ll send you HTTP(s) POST requests that look like the below for each type. Note with each call, you’ll also receive a context object that provides information about the user’s device, IP address, etc. As you start experimenting, we recommend trying the Webhooks destination with RequestBin.com and ultrahook to immediately start seeing requests coming through.

Webhooks timeouts

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

Page

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

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

{
    "version"       : 1,
    "type"          : "page",
    "userId"        : "019mr8mf4r",
    "properties"    : {
        "path"      : "/pricing",
        "referrer"  : "https://segment.com",
        "title"     : "Segment Pricing",
        "url"       : "https://segment.com/pricing"
    },
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Screen

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

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

{
    "version"   : 1,
    "type"      : "screen",
    "userId"    : "019mr8mf4r",
    "name"      : "Main Screen",
    "timestamp" : "2012-12-02T00:30:08.276Z",
    "context"   : {
        "device"     : {
            "model"  : "x86_64",
            "type"   : "ios"
        },
        "os"         : {
            "name"   : "iPhone OS",
            "version": "7.1"
        },
        "app"        : {
            "build"  : "88",
            "name"   : "YourApp",
            "version": "2.0.0"
        }
    }
}

Identify

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

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

{
    "version"   : 1,
    "type"      : "identify",
    "userId"    : "019mr8mf4r",
    "traits"    : {
        "email"            : "achilles@segment.com",
        "name"             : "Achilles",
        "subscriptionPlan" : "Premium",
        "friendCount"      : 29
    },
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Track

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

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

{
    "version"    : 1,
    "type"       : "track",
    "userId"     : "019mr8mf4r",
    "event"      : "Purchased an Item",
    "properties" : {
        "revenue"        : "39.95",
        "shippingMethod" : "2-day"
    },
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Alias

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

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

{
    "version"   : 1,
    "type"      : "alias",
    "Previous ID"      : "previousId",
    "User ID"        : "userId",
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Group

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

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

{
    "version"   : 1,
    "type"      : "group",
    "groupId"   : "0e8c78ea9d97a7b8185e8632",
    "userId"    : "019mr8mf4r",
    "traits"    : {
        "name"             : "Initech",
        "industry"         : "Technology",
        "employees"        : 329,
        "plan"             : "Enterprise",
        "total billed"     : 830
    },
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Delete

When you create a deletion request, for each affected source that has webhooks enabled we will forward a notification so that you can kick off any automations needed on your side. An example call would look like:

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

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

{
    "type"      : "delete",
    "userId"    : "019mr8mf4r",
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Appendices

Authentication

If you want to authenticate the requests being sent to your webhook endpoint, you can input a sharedSecret in the advanced option settings. If you provide this, we will sign your requests using the shared secret and the body of the request, and add that as the ​X-Signature​ header. We calculate 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:

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

if (signature === digest) {

 // do cool stuff

}

SSL Certification

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.

Sending to multiple webhooks

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

Note: If sending a message to any of the webhooks succeed, we consider the message to be successfully processed and won’t retry the request to the other webhooks. If your webhooks aren’t robust, you should consider using our Iron.io destination.

Retries

Our webhooks destination will retry any request that returns 5xx errors, multiple times, for a maximum of 4 hours.

Personas

You can send computed traits and audiences generated using Segment Personas to this destination as a user property. To learn more about Personas, contact us for 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, Personas 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), Personas sets that value to false.

When you first create an audience, Personas 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.

Settings

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

Shared Secret

When this is set, we’ll use it to create a hash signature with each payload. See our webhook documentation for more detail.

Webhook URL

The full URL (with http/https protocol) that we can send data to. eg. https://webhooks.company.com/analytics.

Webhooks (max 5)

For each webhook you’d like to enable, enter the full URL (with http/https protocol) that we can send data to. eg. https://webhooks.company.com/analytics. Additionally, you may set static key:value pairs for Headers on the requests. Limited to 5.