Webhooks

Documentation Index

Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

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