Webhooks

Overview

Organisation admins and owners can register webhook endpoints to receive HTTP callbacks when things happen in their organisation - a listing gets published, a bundle gets deployed. Manage them under /v1/webhooks.

Events

An endpoint subscribes to one or more of:

• mcp.published
• mcp.updated
• bundle.created
• bundle.updated
• bundle.deployed

Creating an endpoint

POST /v1/webhooks with a target_url and the event types to subscribe to. The response includes a signing secret (whsec_...) in plaintext - this is the only time you'll see it. Store it immediately; it can't be retrieved again afterward, only rotated by creating a new endpoint.

target_url must be a public http:// or https:// address - endpoints pointing at internal or loopback addresses are rejected at creation time, and re-validated again immediately before every dispatch.

Verifying a delivery

Every delivery carries two headers:

• X-Hub-Signature-256: sha256=<hex> - an HMAC-SHA256 signature (GitHub's webhook signing scheme), computed over "{timestamp}." + body using your endpoint's secret.
• X-Webhook-Timestamp - the Unix timestamp used in the signed string, so a captured signature can't be replayed later against a different payload.

Recompute the signature the same way on your end and compare it to X-Hub-Signature-256 before trusting a payload.

Testing a receiver

POST /v1/webhooks/{id}/ping sends a synthetic, fully-signed test payload to your endpoint immediately and returns the result synchronously - it does not appear in your delivery history, since it isn't a real event.

Retries

Failed deliveries retry up to 5 times, on this schedule from the first failure: 1s, 5s, 30s, 2m, 10m. Only 429 and 5xx responses (plus timeouts and connection failures) are retried - any other 4xx is treated as a misconfiguration on your end and is not retried.

Delivery history

GET /v1/webhooks/{id}/deliveries returns your endpoint's most recent 100 delivery attempts, including status code, error, duration, and whether each attempt succeeded - useful for debugging a receiver that's rejecting or timing out on deliveries.