Webhooks
Les webhooks envoient une requête à votre serveur lorsqu’un changement survient dans votre centre d’aide, par exemple lorsqu’un article est publié, qu’un lecteur laisse un commentaire ou qu’une tâche Fern est terminée. Utilisez-les pour reconstruire un index de recherche, synchroniser des articles avec votre produit ou publier un message dans un canal d’équipe.
Les propriétaires et les administrateurs ajoutent des points de terminaison dans Paramètres > Espace de travail > Développeurs, sous Webhooks. Un développeur peut également les gérer avec une clé API disposant de l’autorisation webhooks:manage.
Événements
Événement | Envoyé lorsque |
|---|---|
| Un article est publié, y compris lors de chaque nouvelle publication d’un article en ligne. Les modifications du contenu sont envoyées lors d’une nouvelle publication. |
| Le slug, les paramètres SEO ou l’emplacement d’un article en ligne changent. Les modifications apportées aux brouillons ne déclenchent aucun envoi. |
| Un article est dépublié. |
| Un article est supprimé, ainsi qu’une fois par article lorsqu’une collection est supprimée. Les articles supprimés peuvent être restaurés pendant 30 jours. |
| Un article supprimé est restauré. |
| Une traduction est publiée. |
| Une entrée du journal des modifications est publiée pour la première fois. Les modifications ultérieures ne la renvoient pas. Chaque publication d’une entrée envoie également |
| Un lecteur évalue un article ou laisse un commentaire. |
| La révision d’une tâche Fern est publiée et la tâche est terminée. |
Abonnez-vous à * pour recevoir tous les événements.
La requête
Ferndesk envoie une requête POST avec un corps JSON à votre point de terminaison HTTPS. Tous les événements ont la même enveloppe, et data varie selon l’événement.
{
"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"
}
}Événement | Champs dans data |
|---|---|
événements d’article |
|
|
|
|
|
|
|
|
|
Si le corps dépasse 256 Ko, il est envoyé avec data remplacé par {"truncated": true}. Récupérez plutôt l’objet via l’API.
Trouver votre secret de signature
Chaque webhook possède son propre secret de signature, qui commence par whsec_. Les propriétaires et les administrateurs le trouvent en modifiant le webhook dans Paramètres > Espace de travail > Développeurs > Webhooks. Il reste masqué jusqu’à ce que vous choisissiez Afficher dans son menu. Copier le copie sans l’afficher. Lorsque vous ajoutez un webhook, sa fenêtre de dialogue reste ouverte afin que vous puissiez copier immédiatement le nouveau secret.
Un webhook créé avec POST /webhooks reçoit son secret une seule fois, dans la réponse. Vous pouvez également le retrouver plus tard dans l’application.
Vérifier la signature
Ferndesk signe chaque requête selon le protocole Standard Webhooks, celui utilisé par Svix. Chaque requête comporte trois en-têtes :
En-tête | Valeur |
|---|---|
| L’identifiant de l’événement ( |
| Heure d’envoi de cette tentative, en secondes Unix. Chaque nouvelle tentative est signée à nouveau avec un horodatage différent. |
| Une ou plusieurs valeurs |
Lisez le corps brut de la requête avant de l’analyser. Un corps analysé puis reconverti en JSON ne correspondra pas.
Construisez le texte signé : la valeur de
webhook-id, un point, la valeur dewebhook-timestamp, un point, puis le corps brut.Retirez
whsec_du secret et décodez le reste en base64. Vous obtenez la clé.Calculez le HMAC-SHA256 du texte signé avec la clé, puis encodez-le en base64.
Comparez-le à chaque valeur
v1dewebhook-signatureà l’aide d’une comparaison à temps constant. Acceptez la requête si l’une d’elles correspond.Rejetez la requête si
webhook-timestampdiffère de plus de 5 minutes de l’horloge de votre serveur. Cela empêche la relecture d’anciennes requêtes.
La méthode la plus simple consiste à utiliser la bibliothèque Standard Webhooks ou Svix, qui effectue toutes ces opérations, y compris la vérification de l’horodatage. Avec Svix (npm install svix), verify déclenche une erreur si la signature ou l’horodatage est incorrect. Le deuxième onglet effectue les mêmes vérifications avec node:crypto uniquement.
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);Faire tourner le secret
Choisissez Faire tourner dans le menu du secret de signature. Le nouveau secret prend immédiatement le relais. L’ancien reste valide pendant 24 heures ; durant cette période, chaque livraison comporte deux signatures, une pour chaque secret. Ajoutez le nouveau secret à votre serveur avant la fin des 24 heures.
Si vous effectuez une nouvelle rotation dans les 24 heures, l’ancien secret cesse immédiatement de fonctionner. La rotation s’effectue uniquement dans l’application. L’API ne permet pas de faire tourner un secret.
Livraison et nouvelles tentatives
Toute réponse 2xx reçue dans les 10 secondes est considérée comme une livraison réussie. Les redirections ne sont pas suivies.
Une livraison échouée fait l’objet de 5 nouvelles tentatives, après 30 secondes, 5 minutes, 30 minutes, 2 heures et 12 heures.
Les livraisons peuvent arriver dans le désordre et parfois plusieurs fois.
Après 50 tentatives échouées consécutives, le point de terminaison est désactivé. Réactivez-le dans l’application ou avec
PATCH /webhooks/:idet"enabled": true.Les URL des points de terminaison doivent utiliser HTTPS et pointer vers une adresse publique.
Gérer les points de terminaison avec l’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"]}'Requête | Fonction |
|---|---|
| Crée un point de terminaison à partir de |
| Répertorie les points de terminaison, du plus récent au plus ancien. |
| Un point de terminaison et ses 20 dernières livraisons. |
| Modifie |
| Supprime le point de terminaison. Les livraisons cessent et le secret devient invalide. |
| Envoie un événement |
| Une livraison, avec son état, son code de réponse et ses tentatives. |
Dans l’application, le menu d’un point de terminaison propose Envoyer un événement de test et Afficher les livraisons. Les clés et les autorisations sont indiquées dans Authentification.