Webhooks Destination


Segment Webhooks submit real-time user data to your own HTTP endpoints. A Webhook is an HTTP callback: a simple event-notification via 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, please let us know!

Getting Started

The first step is to make sure Webhooks supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

Web Mobile Server
📱 Device-mode
☁️ Cloud-mode
  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “Webhooks” within the Destinations Catalog and confirm the Source you’d like to connect 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.

Page

If you haven’t had a chance to review our spec, please 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/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

If you haven’t had a chance to review our spec, please 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/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"
        }
    }
}

Identify

If you haven’t had a chance to review our spec, please 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/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

If you haven’t had a chance to review our spec, please 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/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

If you haven’t had a chance to review our spec, please 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/version
Content-Type: application/json
{
    "version"   : 1,
    "type"      : "alias",
    "Previous ID"      : "previousId",
    "User ID"        : "userId",
    "timestamp" : "2012-12-02T00:30:08.276Z"
}

Group

If you haven’t had a chance to review our spec, please 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/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"
}

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/version
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, 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.

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 through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Settings

Segment lets you change these destination settings from 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

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account