Skip to main content

Webhooks
beta

GrowthBook has event-based webhooks that trigger a script on your server whenever something changes within GrowthBook. It is currently in beta as we add support for more event types and create better documentation and examples.

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.

This page is also where you can view the shared secret used to verify requests (see below) and see the status of your webhook and any errors.

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.

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}`);
});

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.

Supported Event Types​

We currently support the following event types:

  • feature.created
  • feature.updated
  • feature.deleted
  • experiment.created
  • experiment.updated
  • experiment.deleted

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

Examples​

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.