Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Webhooks

Use the webhooks API to store tenant-level job result destinations that receive job.completed and job.failed events.
All routes on this page require x-api-key.

How webhook delivery works

Libretto Cloud supports multiple stored webhook endpoints per tenant. Every active stored endpoint receives the event payload.
Webhook delivery order is:
  1. If a job has callback_url and callback_secret, Libretto Cloud delivers only to that per-job callback.
  2. Otherwise, Libretto Cloud delivers to every active stored webhook endpoint for the tenant.
  3. If skip_callbacks is true, Libretto Cloud does not deliver callbacks or stored webhooks.
Use stored webhook endpoints for long-lived production destinations. Use callback_url and callback_secret on jobs/create or schedules/create when you want a one-off or environment-specific callback, such as a dev endpoint.

Create a stored webhook endpoint

Use POST /v1/webhooks/create to create a stored webhook endpoint.

POST /v1/webhooks/create

Create a stored webhook endpoint.
Request fields:
  • url
  • signing_secret
  • description: optional
  • active: optional, default true
Response fields:
  • success
  • webhook_endpoint_id
  • message

POST /v1/webhooks/list

List stored webhook endpoints for the current tenant.
Response fields:
  • webhook_endpoints
Each endpoint entry includes:
  • webhook_endpoint_id
  • url
  • description
  • active
  • created_at
  • updated_at

POST /v1/webhooks/update

Update a stored webhook endpoint.
Request fields:
  • id
  • url: optional
  • signing_secret: optional
  • description: optional
  • active: optional
Response fields:
  • success
  • message

POST /v1/webhooks/delete

Delete a stored webhook endpoint.
Request fields:
  • id
Response fields:
  • success
  • message

Delivered payload

Stored webhook endpoints receive:
  • event: job.completed or job.failed
  • job_id
  • nonce
  • workflow
  • deployment_id
  • status
  • result
  • error
  • mapped_stack
The request includes:
  • x-webhook-signature: HMAC SHA-256 of the JSON body using the stored signing_secret
  • x-event-type: the event name
Jobs and Logs
See the jobs API that triggers webhook delivery.
Schedules
Use per-schedule callbacks for recurring runs.
Libretto Cloud API overview
See the shared request format.
Powered byHolocron