Webhooks
Webhooks senden eine Anfrage an Ihren Server, wenn sich etwas in Ihrem Hilfe-Center ändert, zum Beispiel wenn ein Artikel veröffentlicht wird, ein Leser Feedback hinterlässt oder eine Fern-Aufgabe abgeschlossen wird. Verwenden Sie sie, um einen Suchindex neu aufzubauen, Artikel mit Ihrem Produkt zu synchronisieren oder Beiträge in einem Teamkanal zu veröffentlichen.
Inhaber und Administratoren fügen Endpunkte unter Einstellungen > Arbeitsbereich > Entwickler > Webhooks hinzu. Entwickler können sie auch mit einem API-Schlüssel verwalten, der den Bereich webhooks:manage hat.
Ereignisse
Ereignis | Gesendet, wenn |
|---|---|
| Ein Artikel veröffentlicht wird, einschließlich jeder erneuten Veröffentlichung eines bereits veröffentlichten Artikels. Inhaltsänderungen werden als neue Veröffentlichung übermittelt. |
| Der Slug, die SEO-Einstellungen oder die Platzierung eines veröffentlichten Artikels geändert werden. Änderungen an Entwürfen lösen nichts aus. |
| Ein Artikel zurückgezogen wird. |
| Ein Artikel gelöscht wird sowie einmal pro Artikel, wenn eine Sammlung gelöscht wird. Gelöschte Artikel können 30 Tage lang wiederhergestellt werden. |
| Ein gelöschter Artikel wiederhergestellt wird. |
| Eine Übersetzung veröffentlicht wird. |
| Ein Changelog-Eintrag zum ersten Mal veröffentlicht wird. Spätere Änderungen lösen keine erneute Übermittlung aus. Jede Veröffentlichung eines Eintrags sendet auch |
| Ein Leser einen Artikel bewertet oder einen Kommentar hinterlässt. |
| Die Prüfung einer Fern-Aufgabe veröffentlicht und die Aufgabe abgeschlossen wird. |
Abonnieren Sie *, um alle Ereignisse zu erhalten.
Die Anfrage
Ferndesk sendet eine POST-Anfrage mit einem JSON-Body an Ihren HTTPS-Endpunkt. Alle Ereignisse haben denselben Umschlag; data hängt vom Ereignis ab.
{
"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"
}
}Ereignis | Felder in data |
|---|---|
Artikelereignisse |
|
|
|
|
|
|
|
|
|
Ein Body mit mehr als 256 KB wird gesendet, wobei data durch {"truncated": true} ersetzt wird. Rufen Sie das Objekt stattdessen über die API ab.
Signaturgeheimnis finden
Jeder Webhook hat ein eigenes Signaturgeheimnis, das mit whsec_ beginnt. Inhaber und Administratoren finden es, wenn sie den Webhook unter Einstellungen > Arbeitsbereich > Entwickler > Webhooks bearbeiten. Es bleibt verborgen, bis Sie im Menü Anzeigen auswählen. Mit Kopieren wird es kopiert, ohne es anzuzeigen. Wenn Sie einen Webhook hinzufügen, bleibt der Dialog geöffnet, sodass Sie das neue Geheimnis sofort kopieren können.
Ein mit POST /webhooks erstellter Webhook gibt sein Geheimnis einmalig in der Antwort zurück. Sie können es später auch in der App finden.
Signatur überprüfen
Ferndesk signiert jede Anfrage nach dem Standard-Webhooks-Schema, das auch Svix verwendet. Jede Anfrage enthält drei Header:
Header | Wert |
|---|---|
| Die Ereignis-ID ( |
| Unix-Zeit in Sekunden, zu der dieser Übermittlungsversuch gesendet wurde. Jeder Wiederholungsversuch wird mit einem neuen Zeitstempel signiert. |
| Ein oder mehrere durch Leerzeichen getrennte |
Lesen Sie den unverarbeiteten Anfrage-Body, bevor Sie ihn parsen. Ein Body, der geparst und wieder in JSON umgewandelt wurde, stimmt nicht überein.
Erstellen Sie den signierten Text: den Wert von
webhook-id, einen Punkt, den Wert vonwebhook-timestamp, einen Punkt und dann den unverarbeiteten Body.Entfernen Sie
whsec_aus dem Geheimnis und dekodieren Sie den Rest aus Base64. Das ist der Schlüssel.Berechnen Sie den HMAC-SHA256 des signierten Textes mit dem Schlüssel und kodieren Sie das Ergebnis in Base64.
Vergleichen Sie ihn mit jedem
v1-Wert inwebhook-signaturemithilfe eines zeitkonstanten Vergleichs. Akzeptieren Sie die Anfrage, wenn einer der Werte übereinstimmt.Weisen Sie die Anfrage zurück, wenn
webhook-timestampmehr als 5 Minuten von der Uhr Ihres Servers abweicht. So wird verhindert, dass alte Anfragen erneut abgespielt werden.
Am einfachsten geht das mit der Bibliothek von Standard Webhooks oder Svix, die all diese Schritte einschließlich der Zeitstempelprüfung übernimmt. Bei Svix (npm install svix) löst verify einen Fehler aus, wenn die Signatur oder der Zeitstempel nicht stimmt. Der zweite Tab führt dieselben Prüfungen ausschließlich mit node:crypto durch.
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);Geheimnis rotieren
Wählen Sie im Menü des Signaturgeheimnisses Rotieren. Das neue Geheimnis wird sofort aktiv. Das alte bleibt 24 Stunden lang gültig; während dieser Zeit enthält jede Zustellung zwei Signaturen, eine für jedes Geheimnis. Hinterlegen Sie das neue Geheimnis auf Ihrem Server, bevor die 24 Stunden ablaufen.
Wenn Sie innerhalb von 24 Stunden erneut rotieren, wird das älteste Geheimnis sofort ungültig. Die Rotation ist nur in der App möglich. Über die API kann ein Geheimnis nicht rotiert werden.
Zustellung und Wiederholungsversuche
Jede 2xx-Antwort innerhalb von 10 Sekunden gilt als zugestellt. Weiterleitungen werden nicht verfolgt.
Eine fehlgeschlagene Zustellung wird nach 30 Sekunden, 5 Minuten, 30 Minuten, 2 Stunden und 12 Stunden insgesamt 5-mal erneut versucht.
Zustellungen können in beliebiger Reihenfolge und gelegentlich mehrfach eintreffen.
Nach 50 fehlgeschlagenen Versuchen in Folge wird der Endpunkt deaktiviert. Aktivieren Sie ihn in der App oder mit
PATCH /webhooks/:idund"enabled": trueerneut.Endpunkt-URLs müssen HTTPS verwenden und zu einer öffentlichen Adresse aufgelöst werden können.
Endpunkte mit der API verwalten
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"]}'Anfrage | Funktion |
|---|---|
| Erstellt einen Endpunkt mit |
| Listet Endpunkte auf, die neuesten zuerst. |
| Ein Endpunkt und seine letzten 20 Zustellungen. |
| Ändert |
| Löscht den Endpunkt. Zustellungen werden eingestellt und das Geheimnis wird ungültig. |
| Sendet ein |
| Eine Zustellung mit Status, Antwortcode und Wiederholungsversuchen. |
In der App enthält das Menü eines Endpunkts die Optionen Testereignis senden und Zustellungen anzeigen. Schlüssel und Berechtigungsbereiche finden Sie unter Authentifizierung.