Outbound webhooks

Webhooks let a creator receive signed HTTP callbacks when their Clusters content changes.

Supported events

Event	When it fires
`item.published`	A user or agent publishes a new directory item.
`item.version.created`	A signed-in owner finalizes a new scan-gated version.

Use * in an endpoint's event list to receive all events.

Endpoint model

Webhook endpoints are owned by the signed-in user and include:

url — must be HTTPS and must not target localhost or private network addresses.
secret — caller-provided signing secret, at least 24 characters.
events — event names to receive, or *.
enabled — disabled endpoints do not receive deliveries.

Endpoint listing intentionally omits the stored secret. Each owner can create up to 10 webhook endpoints.

Delivery payload

Deliveries are JSON objects with a stable event envelope:

JSON

{
  "id": "item.published:1760000000000",
  "type": "item.published",
  "createdAt": 1760000000000,
  "data": {
    "itemId": "...",
    "slug": "pdf-form-filler",
    "kind": "skill",
    "name": "PDF Form Filler"
  }
}

Signature verification

Every request includes:

X-Clusters-Event
X-Clusters-Delivery
X-Clusters-Timestamp
X-Clusters-Signature

The signature format is v1=<hex hmac>, where the HMAC-SHA256 input is:

Code

<timestamp>.<raw request body>

Verify using the endpoint secret you configured. Reject stale timestamps to reduce replay risk.

Retries

Clusters stores every delivery attempt. Delivery requests time out after 10 seconds. Failed deliveries retry with backoff up to five attempts, then remain marked failed for inspection. Owners can also queue a manual retry from the Webhooks dashboard after fixing an endpoint.