Webhooks

Webhooks let ywork notify your application when events happen in your workspace, so you don’t have to poll the API. When a subscribed event occurs, ywork sends an HTTP POST request to the URL you configure.

Creating a webhook

Register an endpoint and the events you want to receive:

curl -X POST https://docs.ywork.dev/api/v1/webhooks \
  -H "Authorization: Bearer ywork_sk_live_2f8c1b9a4d7e6031" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/ywork",
    "events": ["task.created", "task.updated"]
  }'

Available events

Event	Sent when…
task.created	A task is created.
task.updated	A task is updated.
task.deleted	A task is deleted.
project.created	A project is created.
project.updated	A project is updated.

Delivery payload

Each delivery is a JSON body describing the event and the affected resource:

{
  "id": "evt_6Yb2Rn8kLp",
  "type": "task.created",
  "created_at": "2026-01-14T12:00:00Z",
  "data": {
    "id": "tsk_5Qm9Wp1xTr",
    "object": "task",
    "project_id": "prj_8Hs2Kd0aZq",
    "title": "Ship the new landing page",
    "status": "open"
  }
}

Verifying deliveries

Every request includes an X-ywork-Signature header — an HMAC-SHA256 of the raw request body, signed with your webhook’s signing secret. Recompute the signature on your side and compare it in constant time before trusting the payload.

Responding

Return a 2xx status code within 5 seconds to acknowledge receipt. If your endpoint fails or times out, ywork retries with exponential backoff for up to 24 hours.