Browse the API docs
Endpoint reference

Webhooks

The Crayo Webhooks API registers https endpoints that receive a signed POST when a render, AutoClip job, speech enhancement or tracker refresh finishes. Verify the crayo-signature header with the secret returned once at registration.

Create webhook

POST/v1/webhooks

Registers an https endpoint of yours to receive events. The signing secret comes back once, in this response, and is never shown again, so store it before you do anything else.

  • Store the secret now. Listing webhooks later returns only a masked prefix.
Credits:
Free
Rate limit:
Default tier, 2/s and 50/min

Parameters

NameInTypeRequiredDescription
urlbodystringYesPublic https URL that will receive POST deliveries.
eventsbodystring[]YesEvents to subscribe to. Non-empty. One or more of: export.completed, export.failed, autoclip.completed, autoclip.failed, speech_enhancer.completed, speech_enhancer.failed, tracker.refreshed, tracker.refresh_failed, tracker.paused, tracker.alert, credits.low.

Request

curl
curl -X POST "https://api.crayo.ai/v1/webhooks" \
  -H "Authorization: Bearer $CRAYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/crayo",
  "events": [
    "export.completed",
    "export.failed"
  ]
}'

Response

200 application/json
{
  "success": true,
  "webhook": {
    "id": "cm7x1p4990001abcd",
    "url": "https://example.com/hooks/crayo",
    "events": [
      "export.completed",
      "export.failed"
    ],
    "disabled": false,
    "created_at": "2026-08-21T13:58:20.000Z",
    "secret": "crayo_whsec_8Kd2mQ1rXv7pLb0aY3sTuW9e"
  }
}

Errors

  • 400VALIDATION_ERRORThe URL is not a valid public https address, or an event name is unknown.
  • 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
  • 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
  • 409WEBHOOK_LIMIT_REACHEDYou already have 5 endpoints registered.
  • 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
  • 500SERVER_ERRORSomething failed on our side. Retry with backoff.

List webhooks

GET/v1/webhooks

Lists your registered endpoints, the events each one is subscribed to, and whether it has been disabled after repeated delivery failures. Secrets are masked.

Credits:
Free
Rate limit:
Default tier, 2/s and 50/min

Request

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

Response

200 application/json
{
  "success": true,
  "webhooks": [
    {
      "id": "cm7x1p4990001abcd",
      "url": "https://example.com/hooks/crayo",
      "events": [
        "export.completed",
        "export.failed"
      ],
      "disabled": false,
      "created_at": "2026-08-21T13:58:20.000Z",
      "secret": "crayo_whsec_8Kd2••••••••"
    }
  ]
}

Errors

  • 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
  • 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
  • 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
  • 500SERVER_ERRORSomething failed on our side. Retry with backoff.

Delete webhook

DELETE/v1/webhooks/{id}

Removes an endpoint and stops all deliveries to it. This is also how you replace a leaked secret: delete the endpoint and register it again to get a new one.

Credits:
Free
Rate limit:
Default tier, 2/s and 50/min

Parameters

NameInTypeRequiredDescription
idpathstringYesThe webhook endpoint id.

Request

curl
curl -X DELETE "https://api.crayo.ai/v1/webhooks/cm7x1p4990001abcd" \
  -H "Authorization: Bearer $CRAYO_API_KEY"

Response

200 application/json
{
  "success": true
}

Errors

  • 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
  • 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
  • 404NOT_FOUNDNo webhook with that id belongs to your account.
  • 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
  • 500SERVER_ERRORSomething failed on our side. Retry with backoff.

Send test delivery

POST/v1/webhooks/{id}/test

Sends a signed test.ping delivery to the endpoint so you can confirm your receiver is reachable and your signature check passes. The test is attempted once rather than retried.

Credits:
Free
Rate limit:
Default tier, 2/s and 50/min

Parameters

NameInTypeRequiredDescription
idpathstringYesThe webhook endpoint id.

Request

curl
curl -X POST "https://api.crayo.ai/v1/webhooks/cm7x1p4990001abcd/test" \
  -H "Authorization: Bearer $CRAYO_API_KEY"

Response

200 application/json
{
  "success": true,
  "delivery_id": "evt_7Yc2mQ1rXv7pLb0a"
}

Errors

  • 401MISSING_API_KEYNo Authorization header was sent, or it does not carry a crayo_sk_ key.
  • 401UNAUTHORIZEDThe key sent is malformed, expired, or revoked.
  • 404NOT_FOUNDNo webhook with that id belongs to your account.
  • 409WEBHOOK_DISABLEDThe endpoint was disabled after repeated failures. Delete it and register it again.
  • 429RATE_LIMITEDOver the rate limit. Wait Retry-After seconds.
  • 500SERVER_ERRORSomething failed on our side. Retry with backoff.
New to the Crayo API? See what it is forUse cases, pricing and the console walkthrough live on the API feature page.

Keep exploring

API docs

Exports

Poll render status and collect the finished video file through the Crayo Exports API, or let the export.completed webhook deliver it.

API docs

AutoClip

Turn a long video asset into captioned vertical shorts with the Crayo AutoClip API. Create a job, poll it or use webhooks, then export each clip.

API docs

View Tracker: Managed (our scheduler)

Create trackers that refresh on your cadence, keep every reading, push webhooks and expose snapshots, events, posts and insights through the Crayo API.

API docs

Getting started

Create an API key on the Crayo Developers page, send it as a bearer token to api.crayo.ai, and learn the rate limits, error envelope and webhooks.

API docs

Account

Reference for GET /v1/account on the Crayo API: plan, credit balances by type, storage usage and the rate limits that apply to your key.

API docs

Assets and Uploads

Import media from a URL or upload bytes through a signed URL, then list, rename and delete the assets every other Crayo API endpoint reads from.

FAQs

Frequent questions

export.completed, export.failed, autoclip.completed, autoclip.failed, speech_enhancer.completed, speech_enhancer.failed, tracker.refreshed, tracker.refresh_failed, tracker.paused, tracker.alert, credits.low.

Read the crayo-signature header, which has the form t=<unix seconds>,v1=<hex>. Compute HMAC-SHA256 over the string <t>.<raw body> with your webhook secret and compare it to v1 using a constant-time comparison.

A delivery has 10 seconds to get a 2xx response and is attempted up to 5 times, backing off exponentially from 30 seconds. An endpoint that fails 20 times in a row is disabled and must be deleted and registered again. The delivery id is stable across retries.

Up to 5 endpoints per account. The secret is returned once by POST /v1/webhooks and masked afterwards, so to rotate it delete the endpoint and register it again.

Still have questions?

Contact our 24/7 support team for any concerns or inquiries.

Get in touch