API reference

Webhooks

A webhook endpoint is a URL that receives signed POST requests when runs change state. See the guide for payloads, signatures, and retries.

Guide

Payload shape, signature verification, and retry behaviour are covered in the webhooks guide. This page documents the management endpoints only.

The webhook endpoint object#

idstringoptional

Unique identifier.

urlstringoptional

The HTTPS URL deliveries are POSTed to.

descriptionstring | nulloptional

Optional label for your own reference.

eventsstring[]optional

Subscribed event types. Any of run.started, run.completed, run.failed, run.waiting_input.

workflow_idstring | nulloptional

When set, only runs of this workflow are delivered. null means all workflows.

activebooleanoptional

Inactive endpoints receive nothing. Set to false to pause; endpoints are also deactivated automatically after 10 consecutive failed events.

consecutive_failuresintegeroptional

Events that failed every retry since the last success.

disabled_atstring | nulloptional

When the endpoint was auto-disabled, if ever.

disabled_reasonstring | nulloptional

Human-readable reason for an automatic disable.

last_delivery_atstring | nulloptional

Timestamp of the most recent delivery attempt.

last_delivery_statusinteger | nulloptional

HTTP status of the most recent attempt; 0 means a network error or timeout.

secretstringoptional

The whsec_… signing secret. Returned only in the create response. Rotate it from the dashboard if lost.

created_atstringoptional

ISO 8601 creation time.

updated_atstringoptional

ISO 8601 last update.

Create an endpoint#

POST/v1/webhooks

Registers a URL. The response includes the signing secret — store it now; it is never shown again. Accounts may have up to 20 endpoints.

Body parameters

urlstringrequired

Absolute https:// URL on a publicly reachable host. Credentials in the URL are rejected.

eventsstring[]required

One or more event types.

descriptionstringoptional

Up to 200 characters.

workflow_idstringoptional

Scope to one of your workflows.

bash

curl -X POST https://loopllama.ai/api/v1/webhooks \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/loopllama/webhook",
    "events": ["run.completed", "run.failed", "run.waiting_input"],
    "description": "Production notifier"
  }'

201 Created

{
  "data": {
    "id": "cm2a1…",
    "url": "https://example.com/loopllama/webhook",
    "description": "Production notifier",
    "events": ["run.completed", "run.failed", "run.waiting_input"],
    "workflow_id": null,
    "active": true,
    "consecutive_failures": 0,
    "disabled_at": null,
    "disabled_reason": null,
    "last_delivery_at": null,
    "last_delivery_status": null,
    "created_at": "2026-09-02T14:00:00.000Z",
    "updated_at": "2026-09-02T14:00:00.000Z",
    "secret": "whsec_9f1c…"
  }
}

List endpoints#

GET/v1/webhooks

Returns all of your endpoints, newest first. Secrets are never included.

bash

curl https://loopllama.ai/api/v1/webhooks \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

Retrieve an endpoint#

GET/v1/webhooks/{id}

bash

curl https://loopllama.ai/api/v1/webhooks/$ENDPOINT_ID \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

Update an endpoint#

PATCH/v1/webhooks/{id}

Partial update. Any of url, events, description, workflow_id, active. Setting active: true on an auto-disabled endpoint re-enables it and resets its failure counter.

bash

curl -X PATCH https://loopllama.ai/api/v1/webhooks/$ENDPOINT_ID \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["run.completed"], "active": true}'

Delete an endpoint#

DELETE/v1/webhooks/{id}

Stops deliveries immediately and removes the endpoint's delivery history.

bash

curl -X DELETE https://loopllama.ai/api/v1/webhooks/$ENDPOINT_ID \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY"

200 OK

{ "data": { "id": "cm2a1…", "deleted": true } }

Permissions

Listing and retrieving endpoints works with any API key. Creating, updating, and deleting requires the key's account to have Member access, matching the rules for workflows and runs.