Webhooks

Webhooks are one way to keep cached feature definitions up-to-date on your servers.

With Webhooks, GrowthBook pushes feature definitions to your servers as soon as they change.

The other way is with the API, where your servers pull feature definitions from GrowthBook in a cronjob (or similar).

Adding a Webhook Endpoint

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

There you can add a webhook endpoint.

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.

Environment and Project Filters

You can optionally filter your webhook to a specific environment and/or project. If specified, only matching features will trigger the webhook and be included in the payload.

Payload

Webhooks will do a POST to the endpoint you provide. The body is a JSON object containing feature definitions in the same format as the API returns.

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.

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 { features } = JSON.parse(payload);
    // TODO: Store in a cache or database

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