Webhooks

Webhooks push events from your workspace to an HTTPS endpoint you control, seconds after they happen.

Create a subscription

Under Settings → Apps → Webhooks → New webhook (or POST /webhooks with the webhooks:manage scope) provide:

• URL — must be https:// on port 443 or 8443 and must not resolve to a private address.
• Events — any subset of the event catalogue.
• Boards — optional filter; empty means all boards.

The response contains the signing secret (whsec_…) exactly once. Store it; you need it to verify signatures.

Delivery

Each event is delivered as POST with a JSON body:

{
  "id": "66dc0a3f8e9b4c1234567890",
  "type": "ticket.state_changed",
  "occurredAt": "2026-09-07T12:05:00Z",
  "workspace": "https://acme.stoneity.com",
  "actor": { "id": 17, "name": "Ayşe Yılmaz" },
  "changes": { "field": "State", "oldValue": "Open", "newValue": "In Progress" },
  "data": { "...ticket representation..." }
}

Headers:

Header	Value
webhook-id	Event id (use as idempotency key)
webhook-timestamp	Unix seconds when the delivery was sent
webhook-signature	v1,<base64 HMAC-SHA256> — see Verifying signatures
Content-Type	application/json
User-Agent	Stoneity-Webhooks/1.0

Respond with any 2xx within 10 seconds. Do the real work asynchronously.

Retries

Delivery is at least once. A non-2xx response or a timeout is retried after 1 min, 5 min, 30 min, 2 h, 8 h and 24 h (7 attempts in total). Retries reuse the same webhook-id, so deduplicate on it.

• 410 Gone disables the subscription immediately.
• 20 consecutive failed deliveries pause the subscription and notify workspace administrators. Resume it from the settings page once your endpoint is healthy.

Delivery log

Every attempt is visible for 30 days under the subscription's Deliveries panel (status, HTTP code, duration, response excerpt, payload) and via GET /webhooks/{id}/deliveries. Any delivery can be re-sent with the same payload.

Secret rotation

Rotate secret issues a new whsec_…. For 24 hours deliveries are signed with both the new and the old secret (two space-separated signatures), so you can switch without downtime.

Testing

Test on a subscription queues a webhook.test event so you can check connectivity and signature verification before real traffic arrives.