The webhook reaction lets you programmatically react to changes in your queries and segments as users take actions.  The details of the update are sent via HTTP to a callback URL that you specify, for you to process in any way you want.

Permutive currently supports only segment webhooks (query webhooks coming soon!). Subscribers to a segment webhook receive updates when a user has performed an event that changes their state for this segment, for example a user entering a 'fashion lovers' segment.

Creating a Webhook Reaction

The config JSON object for a webhook reaction requires the following fields:

The provided callback URL must be a valid URL, capable of receiving HTTP POST requests in JSON format.  During the creation of the webhook, a quick HTTP HEAD request to the callback URL is made to verify the callback server.  If a 200 status code is not returned in the response, then the webhook will not be created.

Receiving Webhook Payloads

Once a webhook reaction is created, an HTTP POST request is made to your callback URL every time there is an update for the resource you have subscribed to.

We sign the body of the POST request with an HMAC SHA256 hex digest, using the secret of the webhook URL to which the payload is being sent. This is done using an additional header:

Each POST request will have a content type of application/json and contain the following fields:

When the callback server receives the POST request, it should respond with a 200-level HTTP status code to acknowledge receipt. If any other response is seen, Permutive will retry 5 times throughout the next 24 hours before stopping.

Segment Webhooks

The data object has the following fields for segment webhooks:

Here is an example segment webhook update:

  "id": "49adcef6-6bbd-47cf-bcdb-40f2c55d47e8",
  "reaction_id": "2a169c50-36f0-11e6-ac61-9e71128cae77",
  "type": "segment",
  "time": "2016-04-21T09:10:44.594Z",
  "data": {
    "segment_id": "223cfd4c-2cb6-4b28-9dea-af8b2ed8e3e7",
    "user_id": "2ff3c50a-ecdb-47a8-a3b7-35da24a26f20",
    "identity": {
      "id": "josh123",
      "properties": {
        "email": ""
    "value": true

Did this answer your question?