Webhooks | Docs

Webhooks send a POST to your endpoint when something finishes, so you do not need to poll.

Events

Event	Sent when
`session.processed`	A session finished processing and its segments are searchable
`session.failed`	Processing stopped; the payload includes the session's `issues`
`export.completed`	An export finished writing
`export.failed`	An export stopped

Create an endpoint

POST/v1/webhook_endpoints

Name	Type	Required	Description
`url`	string	yes	HTTPS URL to call
`events`	array	yes	Event names to send

Shell

curl https://api.rayform.world/v1/webhook_endpoints \
  -H "Authorization: Bearer $RAYFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ml.example.com/hooks/rayform", "events": ["session.processed", "export.completed"]}'

The response includes a secret beginning with whsec_. It is shown once; store it to verify signatures.

Payload

JSON

{
  "id": "evt_01JA9F2KQ8",
  "type": "session.processed",
  "created_at": "2026-10-14T13:58:48Z",
  "data": {
    "object": { "id": "ses_01JA8K2M9Q", "object": "session", "status": "processed", "segment_count": 14 }
  }
}

Verifying signatures

Every request carries a Rayform-Signature header: t=<unix seconds>,v1=<hex HMAC-SHA256>. The signed message is the timestamp, a dot, and the raw request body.

verify.py

import hashlib
import hmac
import time


def verify(body: bytes, header: str, secret: str, tolerance_s: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp, signature = int(parts["t"]), parts["v1"]
    if abs(time.time() - timestamp) > tolerance_s:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Respond with any 2xx within 10 seconds. Failed deliveries are retried with exponential backoff for up to 24 hours. Events can arrive more than once or out of order; use id to deduplicate.