Webhooks

Push events to external systems in real time. Connect Fesk to your own tools, dashboards, or automation pipelines.

Setup

Go to Settings → Outgoing Webhooks and click Add webhook (Admin role required). You'll need:

• Project: the project whose events are sent
• Webhook URL: the endpoint that receives events. HTTPS is recommended, so that payloads cannot be read on the way; plain HTTP is accepted. An address in a private or internal network is refused
• Events: which events to subscribe to
• Webhook Secret (optional): an HMAC secret for signature verification. Leave it empty and Fesk generates one

After you create the webhook, Fesk shows its signing secret. That is the only time it is shown, so copy it then.

The same screen lists every webhook on the account's projects, whoever created it, with its last failed delivery. An admin can deactivate, reactivate or delete any of them there.

A webhook can also be created through the API, with POST /v1/webhooks and an API key that holds the tickets:write scope (keys are generated under Settings → API Keys):

curl -X POST https://api.fesk.io/v1/webhooks \
  -H "Authorization: Bearer ld_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/fesk-webhook", "events": ["ticket.created", "comment.created"], "project_id": 1}'

With a key scoped to a project, project_id can be left out: the webhook is created in the key's project. The answer holds the signing secret, once. The API reference has the request and the answer in full.

Testing a webhook

Send test on a webhook under Settings → Outgoing Webhooks makes one request to its URL and shows the status your endpoint answered with. Through the API the same is POST /v1/webhooks/{id}/test.

The test is signed and has the headers of a real delivery, so your signature check is exercised. Its event is webhook.test, which no webhook subscribes to, and it carries no ticket: an endpoint that acts on ticket events does nothing with it. A test is not retried and is not counted among failed deliveries, and a deactivated webhook can be tested before it is switched on again.

Available events

| Event | Fires when | |-------|-----------| | ticket.created | A new ticket is created | | ticket.updated | Ticket fields change (title, description, priority, tags) | | ticket.deleted | A ticket is deleted | | ticket.status_changed | Ticket moves to a different status | | ticket.assigned | Ticket is assigned or reassigned | | ticket.merged | Tickets are merged into one | | comment.created | A public comment is added to a ticket (internal notes send no event) |

Select one or more events per webhook. You can create multiple webhooks pointing to different URLs with different event sets.

Payload

Each delivery sends a JSON payload with the event's id, the event type, a timestamp, and data. data.ticket is the ticket in its current state, in every event. The fields of the event are beside it: data.comment for a comment, the old and the new status for a status change, the old and the new assignee for an assignment. The X-Webhook-Event header identifies the event type. X-Webhook-Delivery-Id stays the same on every retry of a delivery: keep the ones you have processed and skip one you have seen. X-Webhook-Attempt counts the attempts from 1.

Signature verification

Every delivery includes an X-Webhook-Timestamp header, the Unix time the attempt was sent, and an X-Webhook-Signature-V2 header, the HMAC-SHA256 hex digest of the timestamp, a ., and the raw request body, keyed with your webhook's secret. (If you don't provide a secret when creating the webhook, Fesk generates one and shows it once at creation.) Recompute HMAC-SHA256(secret, timestamp + "." + raw_body) on your end, compare it in constant time, and refuse a timestamp more than a few minutes old, so a delivery someone captured cannot be sent to you again later.

X-Webhook-Signature, the HMAC-SHA256 of the body alone, is still sent for endpoints that check only it, but it does not prove when a delivery was sent. The API reference shows both checks in code.

Retry behavior

Failed deliveries (a non-2xx response, or a timeout after 10 seconds) are retried up to 4 times, for 5 attempts per event: 1 minute, 5 minutes, 30 minutes and 2 hours after the attempt before. An endpoint that is down for up to about two and a half hours still receives the event. After that the delivery is logged as failed; the subscription stays active and keeps receiving future events, so there's no automatic disabling after repeated failures. A delivery given up on can be listed and sent again through the API (GET /v1/webhooks/{id}/deliveries, then POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver), with its first delivery id, so an endpoint that got it after all skips it. To catch up after a long outage, GET /v1/tickets?updated_after=… lists every ticket changed since then.