Skip to main content
Version: Config V1 (legacy)

Notifications - Webhooks

Your application can be notified about Setting value changes in real-time. ConfigCat enables this by calling a public URL of your system (a so-called Webhook). You can add your Webhook URLs in the Dashboard.

Adding Webhook

  1. Go to the Webhooks tab.
  2. Set the Url and the HttpMethod.
  3. Optionally, you can add additional HTTP headers and a body to the request.

Request body with variables

You can specify a Request body that will be sent as the payload of the HTTP request.

ConfigCat will replace the following variables in the request body:

VariableThe values it gets replaced with
##ConfigName##The name of the Config your setting belongs to.
##ConfigId##ID of the Config.
##EnvironmentName##The name of the Environment where the Setting value changed.
##EnvironmentId##ID of the Environment.
##URL##A direct link to the Config in the ConfigCat Dashboard.
##ChangeNotes##The Mandatory notes added to the actual changeset.
##ChangedBy##The name and email address of the user who made the changes.
##ChangeDetails##Details of the change in JSON format including setting name, old, new values and Targeting Rules.
##ChangeDetailsTeams##Details of the change in MS Teams format.
##ChangeDetailsSlack##Details of the change in Slack message format.

The structure of the JSON array injected into the ##ChangeDetails## looks like the following:

[
{
"settingKey":"myAwesomeFeature1",
"event":"changed",
"details":"\r\nmyAwesomeFeature1: false ➔ true"
},
{
"settingKey":"myAwesomeFeature2",
"event":"changed",
"details":"\r\nmyAwesomeFeature2:\r\n Rollout percentage items changed:\r\n + 20% true\r\n + 80% false"
}
]

Testing your Webhook

  1. Change some of your settings in the ConfigCat Dashboard.
  2. Click SAVE & PUBLISH SETTINGS.
  3. Check if your Webhook was called correctly.
info

Developer Tip: Running your Webhook on localhost? Expose it to the public internet temporarily by using a tool like ngrok. This enables ConfigCat to call your webhook even in your local development environment.

Verifying Webhook requests

To ensure the requests you receive are actually sent by ConfigCat, we highly recommend to verify the signature sent in the request headers by comparing it with your own calculated signature.

Each webhook request contains the following headers:

HeaderDescription
X-ConfigCat-Webhook-IDThe webhook request's unique identifier. Different in every request.
X-ConfigCat-Webhook-TimestampThe time the webhook was sent in unix timestamp format. (seconds since epoch)
X-ConfigCat-Webhook-Signature-V1The list of the base64 encoded HMAC-SHA-256 signatures. (comma delimited, 1 signature for each signing key)

Currently the latest (and the only) signature header version is V1. If the signing process is going to be changed in the future, more headers will be added with incremented version postfix.

Example request:

POST /path HTTP/1.1
Host: <your-host>
X-ConfigCat-Webhook-ID: b616ca659d154a5fb907dd8475792eeb
X-ConfigCat-Webhook-Timestamp: 1669580020
X-ConfigCat-Webhook-Signature-V1: RoO/UMvSRqzJ0OolMMuhHBbM8/Vjn+nTh+SKyLcQf0M=,heIrGPw6aylAZEX6xmSLrxIWVif5injeBCxWQ+0+b2U=

Content to sign

The signature is calculated from the content constructed by concatenating the webhook's id, timestamp, and raw body together.

const contentToSign = `${webhookId}${timestamp}${body}`;
Content partDescription
webhookIdThe webhook's identifier received in the X-ConfigCat-Webhook-ID request header.
timestampThe timestamp value received in the X-ConfigCat-Webhook-Timestamp request header.
bodyThe raw body of the received webhook request. If the webhook doesn't have a request body it can be left out.
caution

The signature calculation is sensitive to any changes on the signed content, so it's important to not change the request body before the verification. Otherwise, the calculated signature could be completely different from the value received in the
X-ConfigCat-Webhook-Signature-V1 header.

Calculating signature

ConfigCat uses HMAC with SHA-256 to sign webhooks. You can retrieve the signing key(s) required for the signature calculation from the ConfigCat Dashboard's webhook page.

signing keys
info

For key rotation purposes, you can generate a secondary signing key. In this case ConfigCat sends two signatures (one signed with the primary and one signed with the secondary key) in the X-ConfigCat-Webhook-Signature-V1 header separated by a comma (,):

X-ConfigCat-Webhook-Signature-V1: RoO/UMvSRqzJ0OolMMuhHBbM8/Vjn+nTh+SKyLcQf0M=,heIrGPw6aylAZEX6xmSLrxIWVif5injeBCxWQ+0+b2U=
const crypto = require('crypto');

// retrieved from the ConfigCat Dashboard
const signingKey =
'configcat_whsk_VN3juirnVh5pNvCKd81RYRYchxUX4j3NykbZG2fAy88=';

// retrieved from the the X-ConfigCat-Webhook-Signature-V1 request header
const receivedSignature = 'Ks3cYsu9Lslfo+hVxNC3oQWnsF9e5d73TI5t94D9DRA=';

// retrieved from the the X-ConfigCat-Webhook-ID request header
const requestId = 'b616ca659d154a5fb907dd8475792eeb';

// retrieved from the the X-ConfigCat-Webhook-Timestamp request header
const timestamp = 1669629035;

// the webhook request's raw body
const body = 'examplebody';

const contentToSign = `${requestId}${timestamp}${body}`;

const calculatedSignature = crypto
.createHmac('sha256', signingKey)
.update(contentToSign)
.digest('base64');

console.log(calculatedSignature == receivedSignature); // must be true

Timestamp validation

To prevent replay attacks, you can determine whether the request is within your timeframe tolerance by comparing the timestamp value received in the X-ConfigCat-Webhook-Timestamp header with your system's actual timestamp. If the signature is valid but the timestamp is too old, you can reject the request.

Also, as the timestamp is part of the signed content, an attacker can't change it without breaking the signature.

Retries

When ConfigCat notices that a webhook request might not delivered successfully (either due to network instabilities or when we receive a non-2XX status response), it attempts to retry the request at most 5 times with variable frequency.

Connecting to Slack

A few steps to set up Slack and get a message when a setting changes:

  1. Define a Slack Incoming Webhook and copy the Webhook URL.
  2. Go to the Webhooks tab in the ConfigCat Dashboard.
  3. Create a Webhook and add your Slack URL.
  4. Select POST as HTTP method.
  5. Add a request body like so:
{
"text": "<##URL##|##ConfigName## - ##EnvironmentName##> changed in ConfigCat: \n\n##ChangeDetailsSlack##"
}

Connecting to Microsoft Teams

A few steps to set up Microsoft Teams and get a message when a setting changes:

  1. Define an Incoming Webhook connector in Microsoft Teams and copy the Webhook URL.
  2. Go to the Webhooks tab in the ConfigCat Dashboard.
  3. Create a Webhook and add your Teams URL.
  4. Select POST as the HTTP method.
  5. Add a request body similar to the one below.

Sample request body of the Webhook:

{
"@context": "https://schema.org/extensions",
"@type": "MessageCard",
"themeColor": "0072C6",
"title": "##ConfigName## - ##EnvironmentName##",
"text": "##ChangeDetailsTeams##",
"potentialAction": [
{
"@type": "OpenUri",
"name": "Open Config in ConfigCat Dashboard",
"targets": [
{ "os": "default", "uri": "##URL##" }
]
}
]
}