Skip to main content

Event Webhooks
beta

GrowthBook has event-based webhooks that trigger a script on your server whenever something changes within GrowthBook.

Adding a Webhook​

When logged into GrowthBook as an admin, navigate to Settings → Webhooks.

There you can add a webhook endpoint and select which events you want to be notified about.

Supported Event Types​

We currently support the following event types:

  • feature.created
  • feature.updated
  • feature.deleted
  • experiment.created
  • experiment.updated
  • experiment.deleted
  • experiment.warning
  • user.login

The new webhooks are still in beta and we are always updating the list of supported events.

HTTP parameters​

When creating or updating a webhook, you can select which HTTP method should be used. Available methods are: POST, PUT or PATCH.

You can also add your own custom headers. The format of custom headers is a JSON object of the form:

{
  [Header-Name]: "Header Value",
  ...
}

Slack notifications​

Webhooks can be used to send notifications to slack channels and users with much less overhead than setting up a whole slack integration!

First, you need to follow the instruction from the slack documentation to setup your own slack application and webhooks.

Once you have setup your application on slack, you should be able to copy the application's webhook endpoint. You can then paste it as the endpoint URL of your webhook configuration on GrowthBook.

Next, select the Slack payload. That's it, your endpoint is ready to send Slack notifications!

Discord notifications​

Discord notifications work the same way as Slack notifications. The only difference is that you need to follow the discord documentation on how to setup webhook for your discord server.

Projects, tags and environments filtering​

You can select which notifications should be sent to your webhook according to projects, tags or environments. When set, your webhook will only fire when events associated with the selected items are triggered. If unset, you webhook will fire on all events regardless of the given item.

For instance, if your webhook is configured to fire on feature.created events with Project Apollo as a project filter, only feature.created events related to Project Apollo (and any other selected project) will trigger your webhook. If the projects filter is empty, your webhook will fire for all feature.created events on any project.

Testing your webhook​

Once your webhook is configured, you should be able to test it! Look for the Test button on the webhook's settings page. When clicked, a test event should be delivered to the configured endpoint.

This can be quite helpful to debug and confirm that all the webhook's parameters have been set correctly.

Examples​

Errors and Retries​

If your endpoint returns any HTTP status besides 200, the webhook will be considered failed.

Failed webhooks are tried a total of 3 times using an exponential back-off between attempts.

You can view the status of your webhooks in the GrowthBook app under Settings → Webhooks.

VPCs and Firewalls​

If your webhook endpoint is behind a firewall and you are using GrowthBook Cloud, make sure to whitelist the ip address 52.70.79.40.

Verify Signatures​

Webhook payloads are signed with a shared secret so you can verify they actually came from GrowthBook. The signature is passed in a X-GrowthBook-Signature header.

You can find the signature of a given webhook on its settings page. Look for a random string starting with ewhk_....

Here is example code in NodeJS for verifying the signature. Other languages should be similar:

const crypto = require("crypto");
const express = require("express");
const bodyParser = require("body-parser");

// Retrieve from GrowthBook settings
const GROWTHBOOK_WEBHOOK_SECRET = "abc123";

const port = 1337;
const app = express();

app.post(
  "/webhook",
  bodyParser.raw({ type: "application/json" }),
  (req, res) => {
    const payload = req.body;
    const sig = req.get("X-GrowthBook-Signature");

    const computed = crypto
      .createHmac("sha256", GROWTHBOOK_WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

    if (!crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(sig))) {
      throw new Error("Signatures do not match!");
    }

    const data = JSON.parse(payload);
    // TODO: Do something with the webhook data

    // Make sure to respond with a 200 status code
    res.status(200).send("");
  }
);

app.listen(port, () => {
  console.log(`Webhook endpoint listening on port ${port}`);
});

SDK Webhooks (deprecated)​

GrowthBook has another type of webhook, meant specifically to keep SDKs up-to-date with the latest feature flag states. These have been deprecated in favor of SDK Connections and the GrowthBook Proxy Server. The payload for these legacy webhooks are described below for reference.

Payload​

SDK Webhooks will do a POST to the endpoint you provide. The body is a JSON object containing feature definitions in the same format that SDKs are expecting.

Here's an example payload:

{
  "timestamp": 1625098156,
  "features": {
    "feature1": {
      "defaultValue": true
    }
  }
}

The features field has one entry per feature definition. Features can have the following properties:

  • defaultValue
  • rules[] - Array of feature rules
    • condition - A JSON condition using MongoDB query syntax
    • force - Force a specific value, takes precedence over all other rules besides condition
    • variations[] - Run an experiment and randomly assign one of the specified variations
    • key - When running an experiment, this is the experiment key that will be passed to the tracking callback function
    • weights[] - Determines how traffic is split between variations in an experiment
    • coverage - Specifies what sampling rate (0 to 1) to use for including users in an experiment. A rate of 1 means everyone is included. A rate of 0 means no one is.