webhooks

Register a webhook endpoint

Register a webhook so long-running jobs (render/compose/media) notify you instead of blocking on wait_job. Body: url (https, must pass SSRF checks) + events (see the WebhookEvent enum). DELIVERY: each event is a POST with body { event, timestamp, projectId?, data } and Standard-Webhooks headers webhook-id, webhook-timestamp, webhook-signature: v1,<base64> (+ x-cueframe-event). The secret (whsec_<base64>) is returned ONCE here — verify the raw body with new Webhook(secret).verify(rawBody, headers). ACTIVATION (synchronous, no separate step): on create, CueFrame POSTs a signed webhook.verify challenge; your endpoint must reply 2xx echoing data.token (raw body === token, or JSON {token}/{challenge}). On success the response is status:"active"; otherwise status:"pending" with verification.reason and the webhook receives NO events until it verifies (recover with POST /webhooks/:id/verify — no delete/recreate). Full contract + per-event data shapes: GET /webhooks/events.

post/v1/webhooks

Request

  • Base URL: https://api.cueframe.ai
  • URL: https://api.cueframe.ai/v1/webhooks
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.cueframe.ai/api/auth/mcp/authorize, token URL https://api.cueframe.ai/api/auth/mcp/token, scopes: webhooks:write)
    • API key in header PAYMENT-SIGNATURE

Request body

urlstring uri required
eventsWebhookEvent[] required
settleMsinteger

Example request

{
  "url": "https://hooks.example.com/cueframe"
}

Response

Webhook created (secret returned once).

idstring required
urlstring uri required
eventsWebhookEvent[] required
settleMsinteger required
enabledboolean required
status'active' | 'pending' required

active = ownership verified + receiving events; pending = challenge not echoed, inactive.

secretstring required

Standard Webhooks signing secret, format whsec_<base64>. Returned ONCE at create; rotate = delete + recreate. Every delivery carries webhook-id, webhook-timestamp (unix seconds), and webhook-signature: v1,<base64> (HMAC-SHA256 over {id}.{timestamp}.{rawBody}). Verify with any Standard-Webhooks library (standardwebhooks / svix): new Webhook(secret).verify(rawBody, headers).

Changes

No recorded changes to this operation across all 1 revision of this API.