Do this with AI
Install the cms-webhooks skill from Contentstack agent skills. Then ask your agent:
Our production webhook was disabled as unhealthy. Read its execution log for the last 7 days, group the failures by status code and error, tell me what our receiver did wrong, and list the execution UIDs I should retry once it's fixed. Don't re-enable or retry anything yet.
New to this? Set up your AI workbench first.
Webhooks: allowlisting, signatures and disabled endpoints
Webhooks are the part of a Contentstack setup you forget about until they stop. A search index stops updating, a static site stops rebuilding, and then an email arrives with the subject "webhook disabled due to unhealthy notification endpoint". Most of the time the cause is on the receiving side: a firewall that drops the request, a handler that takes longer than 30 seconds, or a signature check that compares the wrong bytes.
This guide covers getting webhooks through a firewall, verifying the signature in TypeScript, recovering a webhook the circuit breaker disabled, and the payload and timing details that surprise people. It applies to any receiver: a serverless function, a CI trigger, a Launch edge function or your own service.
What you'll learn
How to allow Contentstack webhooks through a firewall
How the retry policy and the circuit breaker decide a webhook is unhealthy
How to re-enable a disabled webhook and replay the events it missed
How to verify the default RSA signature and the HMAC signature in TypeScript
Which payload details trip receivers, and why events can arrive late or twice
Symptoms
What you see | Usually means |
|---|---|
Email: "[stack_name] - [webhook_title] webhook disabled due to unhealthy notification endpoint" | 10 failed deliveries in a row. The webhook is off |
Webhook status Unhealthy in Settings > Webhooks | Same. Nothing is delivered until you re-enable it |
Call status HTTP null in the webhook log | The request never connected: DNS, firewall or TLS |
401 in the webhook log | Your receiver rejected the credentials Contentstack sent |
Requests time out in the log, but your handler finishes eventually | Your endpoint took more than 30 seconds to respond |
crypto.verify() returns false for every request | The bytes or the parameters you verify with don't match what was signed |
The same event arrives more than once | A retry after a timeout or non-2xx response |
An event arrives minutes after the publish | It's in the retry schedule, or it's one of many items in a bulk job or release |
data.entry has fewer fields than expected | Send Concise Payload is on |
environment is a UID where you expected production | publish_details stores environment UIDs |
Why it happens
Contentstack concept: A webhook delivery is a POST with a JSON body. Any 2xx response is a success. A 4xx or 5xx, or no response within 30 seconds, is a failure. A failed delivery is retried four more times, after about 5, 25, 125 and 625 seconds, and then marked as failed.
Separately, Contentstack counts consecutive failed deliveries for the webhook as a whole. Failures caused by a 5xx, a 401, a timeout, an aborted connection or a domain that doesn't resolve all count. After 10 in a row with no success in between, the circuit breaker trips: the webhook is marked Unhealthy, disabled, and one email goes to the addresses under Email Addresses to Notify.
So an endpoint that is down for a deploy, a firewall rule that drops traffic, or a handler that rebuilds a site before it responds can each switch a webhook off. And while it's off, events are not queued for later.
Fix it
Allow Contentstack through your firewall
Contentstack doesn't publish the webhook source IP addresses. Ask Contentstack support for the addresses that apply to your region and allow them on the receiving endpoint.
Treat the IP list as a network filter, not as authentication. Verify the signature too (next section), and add an authentication method on the webhook: Basic Auth is available by default, and Bearer Token and OAuth 2.0 Client Credential can be enabled for your organization through support. Custom headers are a useful extra signal, but the docs are clear that they don't replace signature verification.
For local development, don't open your firewall. Expose your dev server through a tunnel such as ngrok or smee and point a test webhook at it.
Respond within 30 seconds
The most common cause of an unhealthy webhook I see is a receiver that does the work before it answers: rebuild the site, reindex the entry, call three other APIs, then return 200. That works until one run takes 31 seconds.
Verify the request, put the job on a queue, and respond:
import express from "express";
import { isFromContentstack } from "./verify-contentstack"; // see the next section
const app = express();
const rawJson = express.raw({ type: "application/json" }); // keep the exact bytes for verification
app.post("/webhooks/contentstack", rawJson, async (req, res) => {
if (!(await isFromContentstack(req))) return res.status(401).send("invalid signature");
const event = JSON.parse(req.body.toString("utf8"));
await queue.add("contentstack-event", event); // do the slow work elsewhere
res.sendStatus(202);
});Return 401 only for requests that fail verification, never because a downstream service is unavailable. Every 401 and 5xx counts toward the circuit breaker.
Verify the signature
Contentstack signs every webhook. The method is set per webhook in Request Signing Method.
Default (Contentstack Certificate). The signature is in the X-Contentstack-Request-Signature header, prefixed with v1=. It's an RSA-PSS signature over the payload with SHA-256 and a salt length of 32. The public key is served from your region's app host, for example https://app.contentstack.com/.well-known/public-keys.json for AWS North America. Use the host you log in to.
// verify-contentstack.ts
import crypto from "node:crypto";
import type { Request } from "express";
const KEY_URL =
process.env.CONTENTSTACK_PUBLIC_KEY_URL ??
"https://app.contentstack.com/.well-known/public-keys.json";
let publicKey: crypto.KeyObject | undefined;
async function getPublicKey(): Promise<crypto.KeyObject> {
if (publicKey) return publicKey;
const res = await fetch(KEY_URL);
const json = (await res.json()) as { "signing-key": string };
// PEM in PKCS#1 format: -----BEGIN RSA PUBLIC KEY-----
publicKey = crypto.createPublicKey({ key: json["signing-key"], format: "pem", type: "pkcs1" });
return publicKey;
}
export async function isFromContentstack(req: Request): Promise<boolean> {
const header = req.get("X-Contentstack-Request-Signature");
if (!header || !Buffer.isBuffer(req.body)) return false;
const signatures = header
.split(",")
.map((part) => part.trim())
.filter((part) => part.startsWith("v1="))
.map((part) => Buffer.from(part.slice(3), "base64"));
const key = await getPublicKey();
return signatures.some((signature) =>
crypto.verify(
"sha256",
req.body, // the raw bytes, exactly as received
{ key, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 },
signature,
),
);
}The route above mounts express.raw() for exactly this reason: nothing reformats the JSON before you check it.
When verification fails for every request, it's almost always one of these:
The body was re-serialized. A JSON body parser followed by JSON.stringify(req.body) can produce different bytes from what was signed, depending on your framework. Verify the raw body.
Wrong padding or salt length. It's RSA-PSS, not PKCS#1 v1.5 (SHA256withRSA). Leave the salt length at 32. Older samples with other salt values fail.
Wrong key format. The key is PKCS#1 (BEGIN RSA PUBLIC KEY). Load it with type: "pkcs1".
Wrong region. Fetch the key from the app host of the region your stack lives in.
HMAC signature. If your organization enabled HMAC signing under Administration > Security Configuration > HMAC Signing and the webhook uses it, the signature is in x-contentstack-hmac-signature as t=<timestamp>,v1=<signature>. It's an HMAC-SHA256 over ${t}.${rawBody} with your organization's secret. During a key rotation the header carries two v1 values, and a match on either one is valid. In the same verify-contentstack.ts:
export function isValidHmac(header: string | undefined, rawBody: string, secret: string): boolean {
if (!header) return false;
let timestamp = "";
const signatures: string[] = [];
for (const part of header.split(",")) {
const [key, value] = part.trim().split("=");
if (key === "t") timestamp = value;
if (key === "v1") signatures.push(value);
}
if (!timestamp || signatures.length === 0) return false;
const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
return signatures.some(
(sig) => sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex")),
);
}Replay protection. Reject requests that are too old. For the default signature, compare triggered_at in the body with your clock. For HMAC, use t. Keep the tolerance generous enough for the retry schedule if you want retried events to be accepted, or accept them through idempotency instead.
Re-enable a disabled webhook
Fix the cause first. If the endpoint still fails, it collects 10 more failures and gets disabled again.
Open Settings > Webhooks, select the webhook and go to the Log tab. Read the status codes and response bodies of the failed executions. Logs go back 30 days.
Fix what the log shows: a 5xx or timeout in your service, expired credentials behind a 401, or a URL that doesn't resolve.
In the webhook list, open the actions menu and select Enable, or turn on Enable Webhook on the webhook page, and save. That resets the failure count.
Replay the events that failed. Re-enabling doesn't deliver them, and retry doesn't work while the webhook is disabled, so do this after step 3.
To replay from a script, list the failed executions and retry each one:
curl -G "https://api.contentstack.io/v3/webhooks/$WEBHOOK_UID/executions" \
-H "api_key: $CS_API_KEY" \
-H "authorization: $CS_MANAGEMENT_TOKEN" \
--data-urlencode "from=2026-12-01T00:00:00.000Z" \
--data-urlencode 'query={"status":{"$gte":"400","$lte":"599"}}'
curl -X POST "https://api.contentstack.io/v3/webhooks/$EXECUTION_UID/retry" \
-H "api_key: $CS_API_KEY" \
-H "authorization: $CS_MANAGEMENT_TOKEN"The executions call returns up to 100 records per request, and each record's uid is the execution UID you retry. Use your region's API host if your stack isn't in AWS North America. A successful retry returns { "notice": "Webhook retry scheduled" }.
If the outage was long, retrying events one by one may be the wrong tool. For a search index or a static site, a full reindex or rebuild after you re-enable the webhook is often faster and more reliable.
Handle the payload you actually get
The body always has module, event, api_key, data and triggered_at. The rest depends on the event and the webhook settings.
Concise payload. With Send Concise Payload on, data carries identifiers and key metadata instead of the full entry. If your receiver needs field values, fetch the entry from the Delivery API, or turn concise payloads off.
Publish events. A publish payload includes data.environment (with name and uid), data.locale, data.action and data.status. The entry's publish_details is an array, and its environment is a UID. Use data.environment.name when you need the name.
Releases. Items published through a release carry a source object with type: "release" and the release title and uid. One release deploy produces one event per item, environment and locale.
Staged events. publish.start, publish.success and publish.fail (and their unpublish equivalents) are separate events. Subscribe to publish.success if you only want to act on content that went live.
Payload in the log. See Details in the webhook log shows the exact request that was sent, which is the fastest way to answer "is this field in the payload or not".
Expect delays and duplicates
Webhooks fire when the publish job processes an item, not when the editor clicks publish. A bulk publish or a release deploy sends its events as the items complete, so a large job spreads its events over time. A failed delivery can arrive up to about 13 minutes late after the four retries. And a delivery that timed out on your side may have been processed by your code anyway, then retried.
Make the receiver idempotent. A key built from api_key, module, event, the entry or asset uid, its _version, the locale and the environment UID identifies a delivery well enough to drop repeats. For site rebuilds, debounce: collect events for a few seconds and trigger one build, so a 200-item release doesn't start 200 builds.
Check that it worked
The webhook status is back to active in Settings > Webhooks, and the next publish shows 200 in the Log tab.
Your receiver logs one verified request per event. Temporarily flip one byte of a stored payload and run it through isFromContentstack to confirm the check really rejects tampered data.
The executions endpoint with the failure query returns no new records after your fix.
Response times in the log are well under 30 seconds, ideally under one.
Prevent it
Respond with 2xx as soon as the request is verified, and process asynchronously.
Fill in Email Addresses to Notify with a shared inbox or an alerting address, not one person.
Don't let deploys of the receiver take it offline for minutes. Ten failures in a row is not many during a release that publishes a lot of content.
Verify signatures on the raw body, cache the public key, and refetch it if verification starts failing for every request.
Scope webhooks with the narrowest channels and environments you need. Fewer events mean fewer chances to trip the breaker.
If missing an event is unacceptable, reconcile on a schedule with the Sync API or a periodic reindex instead of trusting delivery alone.
Key takeaways
A delivery succeeds on 2xx within 30 seconds. Anything else is retried four times, after about 5, 25, 125 and 625 seconds.
Ten consecutive failures from 5xx, 401, timeouts or unreachable URLs disable the webhook and mark it Unhealthy.
Re-enable first, then retry the failed executions. Missed events are not delivered automatically.
Webhook IP addresses come from Contentstack support. Verify X-Contentstack-Request-Signature with RSA-PSS, SHA-256 and salt length 32, on the raw body.
Expect duplicates and bursts. Make receivers idempotent and debounce rebuilds.
Next steps
If a webhook triggers a rebuild and the site still shows old content, read Published, but my site still shows old content.
To understand why a release produces a burst of events, read Releases, bulk publish and nested reference publishing, explained.
For the delivery and webhook limits in one place, see Contentstack limits on one page.
Frequently asked questions
Does Contentstack publish the IP addresses webhooks come from?
No. Ask Contentstack support for the addresses for your region, and verify the request signature as well, because an IP list alone doesn't prove the payload is intact.
When does Contentstack disable a webhook?
After 10 consecutive failed deliveries caused by 5xx responses, 401 responses, timeouts, aborted connections or a domain that doesn't resolve. A single 2xx resets the count.
Which signature algorithm does the default webhook signature use?
RSA-PSS with SHA-256 and a salt length of 32. The public key comes from /.well-known/public-keys.json on your region's app host.
Do events that fired while a webhook was disabled get delivered after I re-enable it?
No. Re-enable the webhook first, then retry the failed executions from the webhook log or with the retry API.
How long does Contentstack wait for my endpoint to respond?
30 seconds. After that the delivery counts as a failure and goes into the retry schedule.