Ferndesk

Webhooks

Créer un point de terminaison webhook

Enregistrez un point de terminaison pour recevoir les livraisons d’événements. L’URL doit utiliser https:// (http:// pour localhost est autorisé en développement). La réponse inclut le secret de signature — stockez-le pour vérifier les signatures des livraisons. Requiert le scope webhooks:manage.

Scope requis : webhooks:manage

POST /webhooks

Créer un point de terminaison webhook

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>"
}

Point de terminaison créé (avec secret de signature)

Authorizations

  • Authorization string requis header

    Toutes les requêtes nécessitent un jeton Bearer dans l’en-tête Authorization. Les clés API sont préfixées par fdsk_ et doivent rester secrètes. Vous pouvez générer et gérer les clés depuis la page Paramètres développeur.

    Les clés peuvent être limitées à n’importe quel sous-ensemble de ces scopes (chaque endpoint indique le scope requis via x-required-scopes) :

    • content:read : lire et rechercher les articles, collections, sections et traductions du centre d’aide
    • content:write : créer et modifier les brouillons d’articles, les utilisateurs et les tâches ; déplacer les articles et les collections
    • content:publish : publier, dépublier, restaurer et mettre à la corbeille le contenu (appliquer les modifications)
    • analytics:read : lire les rapports, analyses et retours sur les articles du centre d’aide
    • conversations:read : lire les conversations et transcriptions de l’assistant IA
    • webhooks:manage : créer et gérer les abonnements aux webhooks sortants

    Accorder content:write ou content:publish implique content:read. Les clés créées avant la mise en place des scopes ont des scopes null = accès complet (mode hérité).

Request Body

application/json
  • url string requis

    URL de destination. Doit utiliser https:// ; http:// est accepté uniquement pour localhost pendant le développement.

  • events[] string requis array

    Types d’événements auxquels ce point de terminaison est abonné. Utilisez les chaînes de type exactes (par exemple article.published) ou le caractère générique * pour recevoir tous les événements.

  • description string | null

    Libellé lisible facultatif pour le point de terminaison.

Response

application/json
  • id string

    Identifiant du point de terminaison webhook (whep_...).

  • url string

    URL HTTPS qui reçoit les charges utiles webhook envoyées via POST.

  • events[] string array

    Types d’événements abonnés (ou *).

  • enabled boolean

    Indique si le point de terminaison reçoit actuellement des livraisons. Les points de terminaison sont automatiquement désactivés après des échecs persistants.

  • description string | null

    Libellé lisible facultatif.

  • failureCount integer

    Nombre d’échecs consécutifs de livraison. Réinitialisé à 0 après toute réussite ou réactivation.

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

    Date et heure de la désactivation automatique du point de terminaison, le cas échéant.

  • createdAt string

    Horodatage ISO 8601 en UTC.

  • updatedAt string

    Horodatage ISO 8601 en UTC.

  • secret string

    Secret de signature (whsec_...) utilisé pour vérifier les signatures des livraisons. Renvoyé une seule fois, lors de la création du point de terminaison ; stockez-le pour vérifier l’en-tête webhook-signature (il ne sera plus jamais renvoyé lors d’une lecture).