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. |
item.created, item.updated, item.deprecated, item.security_notice, item.suspended | Item lifecycle changes. |
install.created | Someone installs your item. |
purchase.paid, usage.paid, platform_purchase.paid, dependency.settled | Monetization events (x402 settlements, dependency payouts). |
review.created, review.replied | A review is posted on your item, or you reply to one. |
report.created, moderation.action, dispute.created, refund_request.created | Trust & safety events on your content. |
workspace.created, workspace.member_invited, workspace.member_joined | Workspace lifecycle. |
api_key.created, webhook.created | Account/security events. |
Some events are private to the acting user (e.g. a buyer's own usage.paid) and are not fanned out
to a seller's webhook unless the event's visibility allows it. Use * in an endpoint's event list to
receive all events you're eligible for.
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:
{
"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-EventX-Clusters-DeliveryX-Clusters-TimestampX-Clusters-Signature
The signature format is v1=<hex hmac>, where the HMAC-SHA256 input is:
<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.