Ferndesk

Webhooks

Create a webhook endpoint

Register an endpoint to receive event deliveries. The URL must be https:// (localhost http:// is allowed in development). The response includes the signing secret — store it to verify delivery signatures. Requires the webhooks:manage scope.

Required scope: webhooks:manage

POST /webhooks

Create a webhook endpoint

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

Created endpoint (with signing secret)

Authorizations

  • Authorization string required header

    All requests require a Bearer token in the Authorization header. API keys are prefixed with fdsk_ and should be kept secret. You can generate and manage keys from the Developer settings page.

    Keys can be restricted to any subset of these scopes (each endpoint lists the scope it requires via x-required-scopes):

    • content:read: Read and search help center articles, collections, sections, and translations
    • content:write: Create and edit article drafts, users, tasks; move articles and collections
    • content:publish: Publish, unpublish, restore, and trash content (make changes live)
    • analytics:read: Read help center reporting, analytics, and article feedback
    • conversations:read: Read AI assistant conversations and transcripts
    • webhooks:manage: Create and manage outbound webhook subscriptions

    Granting content:write or content:publish implies content:read. Keys minted before scoping have null scopes = full access (legacy mode).

Request Body

application/json
  • url string required

    Destination URL. Must be https://; http:// is accepted only for localhost during development.

  • events[] string required array

    Event types this endpoint subscribes to. Use exact type strings (e.g. article.published) or the wildcard * to receive every event.

  • description string | null

    Optional human-readable label for the endpoint.

Response

application/json
  • id string

    Webhook endpoint ID (whep_...).

  • url string

    HTTPS URL that receives POSTed webhook payloads.

  • events[] string array

    Subscribed event types (or *).

  • enabled boolean

    Whether the endpoint currently receives deliveries. Endpoints auto-disable after sustained failures.

  • description string | null

    Optional human-readable label.

  • failureCount integer

    Consecutive delivery failures. Reset to 0 on any success or on re-enable.

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

    When the endpoint was auto-disabled, if applicable.

  • createdAt string

    ISO 8601 timestamp in UTC.

  • updatedAt string

    ISO 8601 timestamp in UTC.

  • secret string

    Signing secret (whsec_...) used to verify delivery signatures. Returned only once, when the endpoint is created; store it to verify the webhook-signature header (it is never returned again on read).