Skip to main content
GrowthBook has SDK-based webhooks that trigger a script on your server whenever something changes within GrowthBook which will affect that SDK.

Adding a Webhook

When logged into GrowthBook as an admin, navigate to SDK Connections and select an existing SDK Connection. Open the connection’s Webhooks tab and click Add webhook. There are built-in webhook types for syncing to Cloudflare KV, Fastly KV, and Vercel Edge Config. For everything else, you can configure a generic HTTP Endpoint to be hit. Once an SDK webhook is created, the Webhooks tab shows when it last sent successfully, and its ⋮ menu has Test to fire a test event, Edit, and Delete. A custom header or the endpoint can reference a webhook secret as {{ SECRET_KEY }}, so the token itself is never stored on the webhook. GrowthBook warns you when a webhook you save or publish references a secret that doesn’t exist, since it would fail to send.

Drafts and Approval

A webhook belongs to its SDK Connection’s revisions. Adding, changing, or removing one is recorded in the connection’s history and can be reverted, together with any settings changed in the same revision. Adding, editing, or deleting a webhook can be saved to a draft, and it goes live when the draft is published. Until then, the live webhooks keep firing as they are, including one the draft deletes. When the connection requires approval, webhook changes are made in a draft unless you can bypass approval. A webhook that a revert brings back is created again with a new signing key.

VPCs and Firewalls

If you use GrowthBook Cloud and the destination is behind a firewall, allow inbound traffic from 52.70.79.40/32. That is the only address GrowthBook Cloud connects out from — see IP addresses.

Verify Signatures

SDK Webhook payloads are signed with a shared secret so you can verify they actually came from GrowthBook.

Standard Webhooks

We follow the Standard Webhooks specification, so you can use any of their SDKs to verify our webhook signatures.

Custom Verification

Webhook requests sent to your endpoint include 3 headers:
  • webhook-id - The unique id for this event
  • webhook-timestamp - The unix integer timestamp of the event
  • webhook-signature - The signature (format described below)
To create the signature, we concatenate the webhook-id, the webhook-timestamp, and the body contents, all separated by dots (.). Then, we create an HMAC SHA-256 hash of this using the shared secret. What we set in the webhook-signature header is the hashing algorithm identifier for HMAC SHA-256 (v1), followed by a comma (,), followed by the base64-encoded hash from above. For example:
You can find the shared secret via SDK Configuration → SDK Connections, choosing the connection, and opening its Webhooks tab. The secret is in the Shared secret column. Here is example code in NodeJS for verifying the signature. Other languages should be similar:

Errors and Retries

If your endpoint returns any HTTP status besides 200, the webhook will be considered failed. Webhooks are retried up to 2 additional times with an exponential back-off between attempts. Each request waits up to 30 seconds for a response by default. You can set a different timeout (in seconds) per webhook. The maximum is 2 minutes on GrowthBook Cloud and configurable with MAX_WEBHOOK_TIMEOUT_SECONDS when self-hosting. You can view the status of your webhooks on the connection’s Webhooks tab under SDK Connections.

Supported HTTP Methods

  • GET
  • POST
  • PUT
  • DELETE
  • PURGE
  • PATCH

Payload Format

For all methods other than GET, you may send a payload body. By default, webhooks will send in the “Standard” format.

Standard

Follows the Standard Webhooks specification. Includes a JSON-encoded SDK Payload in the data.payload field. Example payload:
The data.payload object contains the exact JSON format that our SDKs are expecting. For example, you can pass this directly into the JavaScript SDK:

Standard (no SDK Payload)

Same as above, but without the data.payload field. Example payload:

SDK Payload

Sends the raw SDK Payload using the same format as our SDK features endpoint. This is usually the correct format if you are using the webhook to set a cache value or assigning key/value storage. Example payload:

Vercel Edge Config

Formats the body to work directly with Vercel’s Edge Config API. Example payload:
In order for this to work properly, you must specify the following options as well, replacing the your_* placeholders with actual values.
  • Endpoint URL = https://api.vercel.com/v1/edge-config/your_edge_config_id_here/items
  • HTTP Method = PATCH
  • Headers = { "Authorization": "Bearer your_vercel_api_token_here" }
  • Payload Key = your_value_key_here (defaults to gb_payload if left blank)
Updating Edge Config items owned by a teamIf you are updating an Edge Config item owned by a team, add ?teamId=your_team_id_here to the end of your Endpoint URL.