Webhooks Destination

Segment makes it easy to send your data to Webhooks (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Webhooks in the format they understand. Learn more about how to use Webhooks with Segment.

Getting Started

You can toggle on Webhooks in Segment just like any other destination.

Once you do so, we’ll immediately start forwarding data to up to five different HTTP endpoints you have specified.

Once you toggle on webhooks, we’ll start sending you requests that we receive on our own API. 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.

Note: As you start experimenting, we recommend trying the Webhooks destination with requestb.in and ultrahook to immediately start seeing requests coming through.

Sending to multiple webhooks

Under advanced settings, you can provide up to 5 webhooks. This will ignore any URL you have set in the basic options.

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.


Identify

POST https://your-webhook-url.com/x
User-Agent: Segment/version
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

POST https://your-webhook-url.com/x
User-Agent: Segment/version
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

POST https://your-webhook-url.com/x
User-Agent: Segment/version
Content-Type: application/json
{
    "version"   : 1,
    "type"      : "alias",
    "Previous ID"      : "previousId",
    "User ID"        : "userId",
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Group

POST https://your-webhook-url.com/x
User-Agent: Segment/version
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"
}

Page

POST https://your-webhook-url.com/x
User-Agent: Segment/version
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

POST https://your-webhook-url.com/x
User-Agent: Segment/version
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"
        }
    }
}

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, please 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.

Retries

Our webhooks destination will retry any failed requests once.


Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

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.

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. https://segment.com/docs/integrations/webhooks/#authentication


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!