Ferndesk

Webhooks

Webhook-Endpunkt erstellen

Registrieren Sie einen Endpunkt für den Empfang von Ereigniszustellungen. Die URL muss https:// verwenden (http:// für localhost ist in der Entwicklung zulässig). Die Antwort enthält das Signatur-secret — speichern Sie es, um Zustellsignaturen zu überprüfen. Erfordert den webhooks:manage-Scope.

Erforderlicher Scope: webhooks:manage

POST /webhooks

Webhook-Endpunkt erstellen

curl --request POST \
  --url 'https://api.ferndesk.com/v1/webhooks' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "value"
}'
{
  "id": "<string>",
  "url": "<string>",
  "events": [
    "<string>"
  ],
  "enabled": true,
  "description": "<string>",
  "failureCount": 1,
  "lastSuccessAt": "<string>",
  "lastFailureAt": "<string>",
  "disabledAt": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "secret": "<string>"
}

Erstellter Endpunkt (mit Signatur-Secret)

Authorizations

  • Authorization string erforderlich header

    Alle Anfragen erfordern ein Bearer-Token im Authorization-Header. API-Schlüssel beginnen mit fdsk_ und sollten geheim gehalten werden. Sie können Schlüssel über die Seite Developer settings erstellen und verwalten.

    Schlüssel können auf eine beliebige Teilmenge dieser Scopes beschränkt werden (jeder Endpunkt führt den erforderlichen Scope über x-required-scopes auf):

    • content:read: Hilfecenter-Artikel, Sammlungen, Abschnitte und Übersetzungen lesen und durchsuchen
    • content:write: Artikelentwürfe, Benutzer und Aufgaben erstellen und bearbeiten; Artikel und Sammlungen verschieben
    • content:publish: Inhalte veröffentlichen, deren Veröffentlichung aufheben, wiederherstellen und in den Papierkorb verschieben (Änderungen live schalten)
    • analytics:read: Hilfecenter-Berichte, Analysen und Artikel-Feedback lesen
    • conversations:read: Unterhaltungen und Transkripte des KI-Assistenten lesen
    • webhooks:manage: Ausgehende Webhook-Abonnements erstellen und verwalten

    Die Vergabe von content:write oder content:publish beinhaltet content:read. Vor der Einführung von Scopes ausgestellte Schlüssel haben null Scopes = vollständiger Zugriff (Legacy-Modus).

Request Body

application/json
  • url string erforderlich

    Ziel-URL. Muss https:// verwenden; http:// wird nur während der Entwicklung für localhost akzeptiert.

  • events[] string erforderlich array

    Ereignistypen, für die dieser Endpunkt abonniert ist. Verwenden Sie exakte Typzeichenfolgen (z. B. article.published) oder den Platzhalter *, um jedes Ereignis zu empfangen.

  • description string | null

    Optionales, für Menschen lesbares Label für den Endpunkt.

Response

application/json
  • id string

    ID des Webhook-Endpunkts (whep_...).

  • url string

    HTTPS-URL, die per POST gesendete Webhook-Nutzdaten empfängt.

  • events[] string array

    Abonnierte Ereignistypen (oder *).

  • enabled boolean

    Gibt an, ob der Endpunkt derzeit Zustellungen empfängt. Endpunkte werden nach anhaltenden Fehlern automatisch deaktiviert.

  • description string | null

    Optionales, für Menschen lesbares Label.

  • failureCount integer

    Aufeinanderfolgende Zustellfehler. Wird bei jedem Erfolg oder bei erneuter Aktivierung auf 0 zurückgesetzt.

  • lastSuccessAt string | null
  • lastFailureAt string | null
  • disabledAt string | null

    Wann der Endpunkt gegebenenfalls automatisch deaktiviert wurde.

  • createdAt string

    ISO-8601-Zeitstempel in UTC.

  • updatedAt string

    ISO-8601-Zeitstempel in UTC.

  • secret string

    Signatur-Secret (whsec_...) zur Überprüfung von Zustellsignaturen. Wird nur einmal zurückgegeben, wenn der Endpunkt erstellt wird; speichern Sie es, um den webhook-signature-Header zu überprüfen (bei späteren Lesevorgängen wird es nie wieder zurückgegeben).