Webhooks

⚠️

Preview — this feature is being built; the design below is the spec.

Webhook endpoints receive signed POST requests when something happens in your workspace. All operations need syntic-beta: webhooks-2026-11-01 while in preview.

Operation	Method and path
Register a webhook	`POST /v1/webhooks`
List webhooks	`GET /v1/webhooks`
Get a webhook	`GET /v1/webhooks/{webhook_id}`
Update a webhook	`PATCH /v1/webhooks/{webhook_id}`
Delete a webhook	`DELETE /v1/webhooks/{webhook_id}`
Rotate signing secret	`POST /v1/webhooks/{webhook_id}/rotate_secret`
Send a test event	`POST /v1/webhooks/{webhook_id}/test`
List deliveries	`GET /v1/webhooks/{webhook_id}/deliveries`
Redeliver an event	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

A delivery

POST /syntic HTTP/1.1
Content-Type: application/json
User-Agent: Syntic-Webhooks/1.0
syntic-webhook-id: whk_01JCA4C6E8G0J2L4N6Q8
syntic-event-id: evt_01JCA5D7F9H1K3M5P7R9
syntic-signature: t=1762300800,v1=3b9a0f5c...

{
  "id": "evt_01JCA5D7F9H1K3M5P7R9",
  "type": "batch.completed",
  "created_at": "2026-11-05T10:00:00Z",
  "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q",
  "data": { "object": { "id": "batch_01JC9...", "type": "batch", "status": "completed" } }
}

data.object is what the matching GET endpoint returned at the time of the event. Payloads carry ids and status, never prompt or output text.

Event types

Event	Sent when
`batch.completed`, `batch.failed`, `batch.expired`, `batch.canceled`	A batch reaches a final state.
`file.expired`	A file is removed at its expiry time.
`session.idle`, `session.requires_action`, `session.error`	An agent session finishes a turn, waits for input or approval, or fails.
`deployment.run.failed`, `deployment.paused`	A scheduled or triggered run fails, or a deployment pauses itself.
`environment.build.succeeded`, `environment.build.failed`	An environment build ends.
`spend.threshold_reached`	Credit spend passes 50%, 80% or 100% of a spend limit.
`credits.low_balance`	The balance falls below the auto-reload trigger without a reload.
`inference_hook.failing`	The inference policy hook has failed for 5 minutes.
`encryption_key.unavailable`	A customer-managed key cannot be used.
`webhook.test`	Sent by Send a test event.

Delivery rules

Answer with any 2xx within 10 seconds.
Failures are retried with growing gaps for up to 3 days.
Delivery is at least once and unordered: deduplicate on syntic-event-id and rely on created_at.
Verify syntic-signature (HMAC-SHA256 over t + "." + body) before trusting a delivery; see Verify signatures.

Delete a batch Register a webhook

Was this page helpful?