Outbound webhooks

Setting one up

• Target URL — where we POST to. Must be reachable from this server (not localhost).
• Events — pick at least one; each says what it carries.
• Applies to — all projects, or scope it to one.
• Send test (the paper-plane icon) posts a sample of the first event, marked "test": true, and tells you what your endpoint answered.

Verifying deliveries came from us

Every request carries an HMAC-SHA256 signature of the raw body, signed with the webhook's own secret (copy it from the list), and a delivery id:

X-Forge-Event: WORK_ITEM_CREATED
X-Forge-Signature: sha256=<hex HMAC of the raw body with your secret>
X-Forge-Delivery: <the same id on every retry of this delivery>

Recompute the HMAC over the exact raw body and compare. Use the delivery id to ignore a repeat.

Payload shape

{
  "event": "WORK_ITEM_CREATED",
  "timestamp": "2026-08-03T18:00:00.000Z",
  "organizationId": "...",
  "workItem": {
    "key": "WEB-42",
    "title": "Login button not clickable on Safari",
    "priority": "HIGH",
    "status": "in_progress",
    "project": { "key": "WEB", "name": "Web App" },
    "assignee": { "name": "Alex Kim", "email": "alex.kim@..." } | null
  }
}

Status and assignment events add changes (from → to); comment events add comment; sprint and release events carry workItem: null with sprint or release and project.

Delivery and retries

• 5-second timeout; a slow or down endpoint never holds up the issue itself.
• No answer, a 5xx or a 429 is retried after 1 minute, 5 minutes, 30 minutes and 2 hours (five tries in all) with the same body and delivery id. Other 4xx answers are not retried — fix the endpoint and use Send test.
• Answering 410 Gone turns the webhook off — the standard way for a subscriber to unsubscribe.
• Regenerating the secret invalidates signature checks against the old one at once.

Zapier and other no-code tools

Create an API token (Settings → API tokens) — it belongs to this workspace and acts with the role of whoever created it. A REST-hook trigger subscribes by creating a webhook through the API and unsubscribes by deleting it; actions call the same API you use.

Authorization: Bearer fk_live_…
POST   /api/v1/webhooks        { "name": "Zapier", "targetUrl": "<hook url>", "events": ["WORK_ITEM_CREATED"] }
DELETE /api/v1/webhooks/<id>
POST   /api/v1/work-items      { "projectKey": "WEB", "type": "TASK", "title": "…" }