Webhooks

Get a message in Slack, Discord, Teams or your own endpoint whenever a bin is published, promoted, rolled back or unpublished.

A webhook tells you when a bin changes. Each publish, promote, rollback and unpublish sends one message, which says what the environment serves now and who changed it:

in Slack
acme/mobile-flags · production is now v13
Promoted from staging v12 by key Promote (was v12)
View in hotcfg

Point a webhook at the channel where your team already talks, and nobody has to watch the dashboard to know that production changed. Or point it at your own endpoint, which gets a signed JSON event, and start a build or post to a tool hotcfg doesn't support.

Webhooks are part of Pro. Only the organization's administrators and owner can add or change them, because a webhook sees every change to the bin, including production.

Add a webhook

  1. Get an incoming webhook URL from the service, as shown below.
  2. In the dashboard, open the bin and go to Webhooks → Add webhook.
  3. Paste the URL. The format is detected from it: Slack, Discord, Teams, Google Chat and Telegram URLs are recognized. For Mattermost, pick the format yourself. Optionally, add a Description that says what the webhook is for, like Releases to #engineering, so your team can tell webhooks apart. It's shown only in the dashboard and never sent.
  4. Choose the environments and events. For example, only production, and only Promote, Rollback and Rollout, to hear about releases and not every staging push. Rollout covers each step of a progressive rollout: started, share changed, completed and aborted.
  5. Press Add webhook, then Send test. A test message should appear in the channel, and the webhook's Recent deliveries shows the receiver's answer.

A bin can have up to 5 webhooks. When you add one, hotcfg shows its signing secret once. Chat services ignore it, but your own endpoint uses it to check that a delivery came from hotcfg.

Warning

A webhook URL is a secret: anyone who has it can post to that channel. hotcfg stores it encrypted, like the signing secret, and shows it masked after you save it (https://hooks.slack.com/…xyz9). To change it, paste the new URL under Edit.

Set up each service

Slack

  1. Go to api.slack.com/apps, choose Create New App → From scratch, and pick your workspace.
  2. Under Incoming Webhooks, turn on Activate Incoming Webhooks.
  3. Choose Add New Webhook, pick the channel, and allow it.
  4. Copy the URL, which starts with https://hooks.slack.com/services/.

Discord

  1. Open the channel's settings (Edit Channel) and go to Integrations → Webhooks.
  2. Choose New Webhook, give it a name such as hotcfg, and choose Copy Webhook URL.

The URL starts with https://discord.com/api/webhooks/. Messages never mention @everyone or anyone else, even if someone's name contains it.

Microsoft Teams

Teams' older "Incoming Webhook" connectors are being retired, so use a workflow:

  1. In the channel, open ⋯ → Workflows, and pick the template Send webhook alerts to a channel.
  2. Name it, pick the team and channel, and choose Add workflow.
  3. Copy the URL it shows. It's on logic.azure.com or powerplatform.com.

Messages arrive as Adaptive Cards, with a View in hotcfg button.

Google Chat

Webhooks in Google Chat need a Google Workspace account.

  1. Open the space, then Apps & integrations → Webhooks (or Manage webhooks).
  2. Choose Add webhook, name it, and save.
  3. Copy the URL, which starts with https://chat.googleapis.com/v1/spaces/.

Mattermost

  1. Go to Integrations → Incoming Webhooks → Add Incoming Webhook, and pick the channel.
  2. Copy the URL, which looks like https://chat.example.com/hooks/xxx.
  3. In hotcfg, set Format to Mattermost. A Mattermost server can be on any domain, so it can't be detected from the URL.

Telegram

  1. Message @BotFather, send /newbot, and copy the bot's token.
  2. Add the bot to the group or channel. In a channel, make it an administrator so it can post.
  3. Find the chat's id. For a public channel, @channelname works. For a group, send a message in it, then open the first URL below in a browser and copy chat.id (group ids are negative).
  4. Use the second URL as the webhook URL.
find the chat's id
https://api.telegram.org/bot<token>/getUpdates
webhook URL
https://api.telegram.org/bot<token>/sendMessage?chat_id=<chat id>

Your own endpoint

Any HTTPS URL that isn't one of the services above gets the JSON format: the event, signed. The endpoint should answer with a 2xx status within 10 seconds, and do slow work afterwards. Tools like Zapier, Make, n8n and Pipedream give you such a URL, and can take it from there.

What gets sent

Each format turns the same event into a message:

EventMessage
Publishproduction is now v13 / Published by Dana (was v12)
Promoteproduction is now v13 / Promoted from staging v12 by key Promote (was v12)
Rollbackproduction rolled back to v11 / Published again as v14 by Dana (was v13)
Unpublishproduction unpublished / v13 is no longer served; unpublished by Dana
Rollout startedproduction v13 rolling out to 10% / Promoted from staging v14 by Dana; the rest still get v12
Rollout changedproduction v13 rolling out to 50% / Changed from 10% by Dana
Rollout completedproduction is now v13 / Rollout completed by Dana (was v12)
Rollout abortedproduction rollout of v13 aborted / Everyone gets v12 again; aborted by Dana
Testtest message from hotcfg / This webhook works. Sent by Dana

"By" names the dashboard user (their name, or email if they have none) or the API key. A change made with the CLI or the GitHub Action shows its key's name, so give your keys names like CI and Promote.

Messages never contain the config itself, only the version numbers and a link to the bin's history in the dashboard. Members who can open it see the diff there. That keeps the contents of a private bin out of chat.

Deleting an environment or a bin sends nothing: the webhooks of a deleted bin are deleted with it.

What your endpoint gets

A JSON-format webhook receives a POST with the event as its body:

POST body
{
  "id": "evt_5f0c9a8e2b7d41a6c3e1f09b",
  "event": "promote",
  "created_at": "2026-11-16T21:04:00Z",
  "bin": { "organization": "acme", "id": "mobile-flags", "name": "Mobile flags" },
  "environment": "production",
  "version": 13,
  "previous_version": 12,
  "promoted_from": { "environment": "staging", "version": 12 },
  "actor": { "type": "api_key", "id": "key_9f3e1a7c", "name": "Promote" },
  "url": "https://hotcfg.run/acme/bins/mobile-flags?env=production&tab=history&v=12"
}
FieldMeaning
idThe event's id. It's the same on every retry of this event, so use it to ignore duplicates.
eventpublish, promote, rollback, unpublish, rollout or test
created_atWhen the change happened (UTC)
binThe organization's slug, and the bin's id and name
environmentThe environment that changed; "" for a test
versionWhat the environment serves now; 0 after an unpublish
previous_versionWhat it served before; 0 if nothing
promoted_fromOn promote: the environment and version that were copied
rolled_back_toOn rollback: the older version that's served again, now as version
rolloutOn rollout: action (started, changed, completed or aborted), the rollout's version, its percent now (100 once completed, 0 once aborted) and, when it changed, previous_percent. version at the top level is what everyone else is served. See Progressive rollouts
actorWho made the change: type is user or api_key. name is empty if they've been deleted since, and so is a deleted user's id
urlThe bin in the dashboard: its history, with the version served before this change selected so its diff and Rollback are one click away, or, while a rollout runs, the Payload tab with its Abort

To read the config itself, fetch it with ?v=<version> and a key, as described in Reading config.

Every delivery, in every format, carries these headers:

HeaderValue
Content-Typeapplication/json
User-Agenthotcfg-webhooks/1 (+https://hotcfg.run/docs/guides/webhooks)
X-Hotcfg-EventThe event type, as in event
X-Hotcfg-DeliveryThe event's id
X-Hotcfg-TimestampWhen this attempt was signed, in Unix seconds
X-Hotcfg-Signaturet=<timestamp>,v1=<signature>, explained next

Check the signature

Anyone who finds your endpoint's URL could post to it. The signature proves a delivery came from hotcfg and wasn't changed on the way. hotcfg signs every delivery with the webhook's secret; your endpoint signs the same bytes with the same secret, and accepts the delivery only if the two signatures match. Check it before you do anything else with the request.

You need three things from the request: the X-Hotcfg-Signature header, the body exactly as it arrived, and the webhook's signing secret, which starts with whsec_. The header looks like this:

X-Hotcfg-Signature
t=1763380000,v1=70f8d7ee406e49dda9491b6d399f03041df4ad08d436043c4a506a0a24c01b9e

t is when the delivery was signed, in Unix seconds. v1 is the signature.

  1. Read t and v1 from the header. Split it at commas, then each part at =. For a day after you change the secret there are two v1 values, one per secret; accept the delivery if either one matches.
  2. Check the time. If t is more than 5 minutes before or after now, refuse the delivery. This stops anyone who captured an old delivery from sending it again.
  3. Build the text to sign: t, a dot, then the body. For example 1763380000.{"id":"evt_…","event":"publish",…}.
  4. Sign it with HMAC-SHA256, using the whole secret, whsec_ included, as the key. Write the result as lowercase hex: 64 characters, like v1.
  5. Compare your result with each v1, using your language's constant-time comparison rather than ==, so the time it takes doesn't give the signature away. If one matches, the delivery is genuine.

You can copy one of these functions instead of writing it. Each follows the steps above:

verify.js
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body as a string, before JSON.parse.
// header: the X-Hotcfg-Signature header. secret: the webhook's whsec_… secret.
export function verifyHotcfg(rawBody, header, secret) {
  // 1. Read t and every v1 from the header.
  const fields = (header ?? "").split(",").map((f) => f.trim().split("="));
  const t = fields.find(([k]) => k === "t")?.[1] ?? "";
  const signatures = fields.filter(([k]) => k === "v1").map(([, v]) => v ?? "");

  // 2. Refuse a delivery signed more than 5 minutes away from now.
  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  // 3 and 4. Sign "<t>.<body>" with the secret, as lowercase hex.
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));

  // 5. Accept if any v1 matches, compared in constant time.
  return signatures.some((s) => {
    const got = Buffer.from(s);
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

When the signature doesn't match

To find out why, press Check a signature on the bin's Webhooks tab and paste the header, the body and the secret your endpoint used. It runs each step above and names what went wrong. The check runs in your browser, so the secret isn't sent anywhere.

Almost every mismatch is one of these:

  • The body was parsed first. Most frameworks parse JSON for you, and turning it back into text changes the spacing and key order, so the signature no longer matches. Read the raw body: express.raw() in Express, request.get_data() in Flask, await request.body() in FastAPI, io.ReadAll(r.Body) in Go.
  • The secret is missing its whsec_ prefix, or belongs to another webhook. Each webhook has its own secret.
  • The signature is compared in another form, such as base64 or uppercase hex. v1 is lowercase hex.
  • The server's clock is off by more than 5 minutes. Keep it in sync with NTP.

To test your code without waiting for a delivery, give it this example. With the time check (step 2) turned off, it must accept it, and refuse it if you change one character of the body:

InputValue
Secretwhsec_0123456789abcdef0123456789abcdef0123456789abcdef
Body{"id":"evt_test","event":"test"}
Headert=1763380000,v1=70f8d7ee406e49dda9491b6d399f03041df4ad08d436043c4a506a0a24c01b9e

Then press Send test on the webhook to try it with a real delivery.

A complete receiver

Put together with Node and Express, a receiver checks the signature, answers at once, and handles each event only once:

server.js
import express from "express";
import { verifyHotcfg } from "./verify.js";

const app = express();
const seen = new Set(); // in production, a table with a unique key on the event id

// The raw body, limited in size: deliveries are a few kilobytes.
app.post("/hotcfg", express.raw({ type: "application/json", limit: "64kb" }), (req, res) => {
  const raw = req.body.toString("utf8");
  // 1. Refuse before parsing anything.
  if (!verifyHotcfg(raw, req.get("X-Hotcfg-Signature"), process.env.HOTCFG_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(raw);
  // 2. Answer right away; hotcfg waits 10 seconds at most.
  res.sendStatus(204);
  // 3. Handle each event once, even when a retry sends it again.
  if (seen.has(event.id)) return;
  seen.add(event.id);
  queueMicrotask(() => handle(event)); // or hand it to your job queue
});

Keep the secret in an environment variable or a secrets manager, never in code, with one secret per webhook. Don't log the X-Hotcfg-Signature header or the secret.

Deliveries don't come from fixed IP addresses, so an IP allowlist won't work: check the signature instead.

Change the secret

Choose New secret on the webhook when the secret may have leaked, or to rotate it. For the next 24 hours, each delivery is signed with both the new and the old secret, as two v1 values, so your endpoint keeps accepting deliveries while you update it. After that, only the new secret signs.

Retries and failures

A delivery succeeds when the receiver answers with a 2xx status within 10 seconds. Anything else, including a redirect, is a failure, and the delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. After 6 attempts over about 15 hours, it's given up. Recent deliveries shows each one's state, the last status code or error, and when the next attempt is due.

If a webhook fails for 3 days without a single success, hotcfg turns it off and marks it Paused: failing, for example when someone deleted the Slack webhook. Fix the receiver, press Send test, then Turn on.

If the administrator who set up a webhook is removed from the organization or made a member, hotcfg turns the webhook off and marks it Paused: admin left, so changes stop going to a URL they chose. Check that the URL is still one your team controls, then Turn on. Whoever turns a webhook on, or changes its URL, is from then on the administrator it belongs to.

A few things to rely on, and not to:

  • Each event is sent at least once. A receiver that answered too slowly can get it again. Use id (or X-Hotcfg-Delivery) to ignore one you've already handled.
  • Order is usually kept, but not guaranteed. One webhook's deliveries are sent oldest first, but a retried one can arrive after a later change. To know which is newest, compare version, or created_at across environments.
  • Changes made while a webhook is off aren't sent later. Turning it back on sends only what happens from then on.
  • On Free, webhooks don't fire. After a downgrade from Pro they're kept, with their secrets and settings, and marked Not firing on Free. They fire again from the next change after you upgrade; changes made while on Free are never sent. See Moving to Free.

Every webhook that's added, changed, given a new secret or deleted is recorded in the audit log.

Last updated 17 November 2026