Webhooks
Webhooks send a request to your server when something changes in your help center, such as an article being published, a reader leaving feedback or a Fern task finishing. Use them to rebuild a search index, sync articles into your product or post to a team channel.
Owners and admins add endpoints in Settings > Workspace > Developers under Webhooks. A developer can also manage them with an API key that has the webhooks:manage scope.
Events
Event | Sent when |
|---|---|
| An article is published, including each republish of a live article. Content edits arrive as a new publish. |
| A live article's slug, SEO settings or placement change. Draft edits send nothing. |
| An article is unpublished. |
| An article is deleted, and once per article when a collection is deleted. Deleted articles can be restored for 30 days. |
| A deleted article is restored. |
| A translation is published. |
| A changelog entry goes live for the first time. Later edits do not send it again. Every publish of an entry also sends |
| A reader rates an article or leaves a comment. |
| A Fern task's review is published and the task is done. |
Subscribe to * to get every event.
The request
Ferndesk sends a POST with a JSON body to your HTTPS endpoint. Every event has the same envelope, and data depends on the event.
{
"id": "whevt_01JZ8M3Q7T2K9V4X6B1N5C8D0E",
"type": "article.published",
"created_at": "2026-11-21T10:15:00.000Z",
"data": {
"id": "art_01JZ8M2W4R6T8Y0U2I4O6P8A1S",
"title": "Reset your password",
"slug": "reset-your-password",
"status": "published",
"version": 4,
"url": "https://help.example.com/reset-your-password-ab12c",
"collection_id": "col_01JZ8M1E3R5T7Y9U1I3O5P7A9S",
"published_by_member_id": "mem_01JZ8M0Q2W4E6R8T0Y2U4I6O8P",
"source": "editor"
}
}Event | Fields in data |
|---|---|
article events |
|
|
|
|
|
|
|
|
|
A body over 256 KB is sent with data replaced by {"truncated": true}. Fetch the object through the API instead.
Find your signing secret
Each webhook has its own signing secret, which starts with whsec_. Owners and admins find it when they edit the webhook in Settings > Workspace > Developers > Webhooks. It stays masked until you choose Reveal in its menu. Copy copies it without showing it. When you add a webhook, its dialog stays open, so you can copy the new secret right away.
A webhook created with POST /webhooks gets its secret once, in the response. You can also find it later in the app.
Verify the signature
Ferndesk signs every request with the Standard Webhooks scheme, the same one Svix uses. Each request has three headers:
Header | Value |
|---|---|
| The event id ( |
| Unix seconds when this attempt was sent. Each retry is signed again with a new timestamp. |
| One or more |
Read the raw request body before you parse it. A body that was parsed and turned back into JSON won't match.
Build the signed text: the
webhook-idvalue, a dot, thewebhook-timestampvalue, a dot, then the raw body.Remove
whsec_from the secret and base64-decode the rest. That is the key.Compute the HMAC-SHA256 of the signed text with the key, and base64-encode it.
Compare it with each
v1value inwebhook-signature, using a constant-time comparison. Accept the request if any one matches.Reject the request if
webhook-timestampis more than 5 minutes from your server's clock. This stops old requests from being replayed.
The easiest way is the Standard Webhooks or Svix library, which does all of this, including the timestamp check. With Svix (npm install svix), verify throws when the signature or timestamp is wrong. The second tab does the same checks with node:crypto only.
import express from 'express';
import { Webhook } from 'svix';
const app = express();
const webhook = new Webhook(process.env.FERNDESK_WEBHOOK_SECRET);
app.post('/webhooks/ferndesk', express.raw({ type: 'application/json' }), (req, res) => {
try {
webhook.verify(req.body, req.headers);
} catch {
return res.status(400).send('Invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
res.sendStatus(200);
});
app.listen(3000);Rotate the secret
Choose Rotate in the signing secret's menu. The new secret takes over at once. The old one keeps working for 24 hours, and during that time each delivery carries two signatures, one for each secret. Put the new secret on your server before the 24 hours run out.
If you rotate again within 24 hours, the oldest secret stops working at once. Rotation is only in the app. The API can't rotate a secret.
Delivery and retries
Any 2xx answer within 10 seconds counts as delivered. Redirects are not followed.
A failed delivery is retried 5 times, after 30 seconds, 5 minutes, 30 minutes, 2 hours and 12 hours.
Deliveries can arrive out of order, and occasionally more than once.
After 50 failed attempts in a row the endpoint is disabled. Re-enable it in the app or with
PATCH /webhooks/:idand"enabled": true.Endpoint URLs must use HTTPS and resolve to a public address.
Manage endpoints with the API
curl -X POST https://api.ferndesk.com/v1/webhooks \
-H "Authorization: Bearer $FERNDESK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhooks/ferndesk", "events": ["article.published", "article.deleted"]}'Request | What it does |
|---|---|
| Creates an endpoint from |
| Lists endpoints, newest first. |
| One endpoint and its last 20 deliveries. |
| Changes |
| Deletes the endpoint. Deliveries stop and the secret stops working. |
| Sends a |
| One delivery, with its status, response code and attempts. |
In the app, an endpoint's menu has Send test event and View deliveries. Keys and scopes are in Authentication.