Webhooks

Delegation and approval events delivered to your endpoint, signed with Delagents-Signature and retried for 24 hours.

4 min read · updated 2026-09-17

Preview: webhooks are part of Business and become available with the API when the workspace app launches. The event names and the body below are the design.

A webhook is an HTTPS endpoint you register. Delagents posts an event to it when a delegation changes state or a checkpoint is raised or answered. Use it to open a card in your own tools, to post to a channel, or to pick up a deliverable the moment it lands.

Events

Event	When it fires
delegation.delegated	A draft was delegated and the first run was queued.
delegation.status_changed	Any move between states, with the from and to states in the data.
delegation.waiting	A checkpoint needs a person. The delegation is Waiting on you.
delegation.done	The requester accepted the deliverables.
delegation.failed	The run failed, with the reason.
delegation.cancelled	Someone canceled the delegation, or it was re-delegated.
approval.requested	A checkpoint card was filed, with the proposed action and its preview.
approval.decided	A person approved, requested changes or rejected, with who and when.
deliverable.created	A file, link, text or data deliverable was added.

The body

{
  "id": "evt_01J...",
  "type": "approval.requested",
  "createdAt": "2026-09-17T10:02:11Z",
  "workspaceId": "ws_01J...",
  "data": {
    "delegationId": "dlg_01J...",
    "approval": {
      "id": "apr_01J...",
      "kind": "ACTION",
      "risk": "external_send",
      "title": "Support triager wants to send this reply",
      "costUsdMicros": "0",
      "expiresAt": "2026-09-24T10:02:11Z"
    }
  }
}

Verifying the signature

Every delivery carries a Delagents-Signature header of the form t=<unix timestamp>,v1=<signature>. The signature is an HMAC-SHA256 over the timestamp, a period and the raw request body, keyed with the endpoint's signing secret. The secret is shown once when you create the endpoint.

Read the t and v1 values from the header.
Concatenate t, a period and the exact raw body you received.
Compute HMAC-SHA256 with your signing secret and compare it to v1 in constant time.
Reject a delivery whose timestamp is old; a window of a few minutes blunts replays.

Retries

Delagents expects a 2xx response. Anything else is retried with exponential backoff for 24 hours. After that the endpoint is disabled and workspace admins are notified; re-enable it under Settings, then API, once it is healthy. Each attempt is listed on the endpoint's page with its status and the time of the next attempt.

Idempotency

Deliveries are at least once. Keep the event id and ignore a second delivery of the same id. Retries can reorder deliveries, so use createdAt when you need a timeline rather than the order of arrival.

Managing endpoints

Admins add, pause and remove endpoints under Settings, then API, and choose which events each one receives. Endpoints must be HTTPS. Signing secrets are stored encrypted and can be rotated from the same page.