Webhooks

Lymo delivers webhooks via Svix. Every delivery carries standard signature headers you can verify with any Svix SDK.

Before you register: hostname allowlist

Webhook destinations are gated by a per-organization hostname allowlist. This is a defense-in-depth check on top of Svix’s own URL validation — it prevents a leaked API key from being turned into an SSRF relay via Svix.

The default allowlist for a new organization is empty, which means every POST /v1/webhooks call fails with 422 invalid_webhook_url until your organization’s allowlist contains the hostname you want to deliver to. Ask your Lymo contact (CSM, admin) to add entries to organization_settings.webhook_allowed_hostnames before you start integrating.

Allowlist rules:

Scheme must be https://.
Exact match: webhook.site permits only webhook.site.
Wildcard subdomain: *.example.com permits a.example.com, foo.bar.example.com, but not the apex example.com.
Matching is case-insensitive and uses punycode form.

Register an endpoint

curl -X POST "$LYMO_BASE/v1/webhooks" \
  -H "Authorization: Bearer $LYMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.your-app.example.com/lymo",
    "events": ["video.analysis.completed"]
  }'

The response includes a secret starting with whsec_. Save it immediately — it is returned only at creation time and is required for signature verification. There is no rotation endpoint today; if you lose or leak it, delete the endpoint and create a new one. Omit events (or pass []) to subscribe to every event type.

Event types

Event	Status	Fires when
`video.ready`	Delivered	Video finishes processing and is analyzable
`video.analysis.completed`	Delivered	`POST /analyses` job succeeds
`video.analysis.failed`	Delivered	`POST /analyses` job fails permanently
`deal.scoring.completed`	Planned (not yet delivered)	`POST /scorings` job succeeds
`deal.scoring.failed`	Planned (not yet delivered)	`POST /scorings` job fails permanently

The deal.scoring.* events are declared in the schema so SDK types remain stable, but the publisher isn’t wired up yet — subscribing to them today produces no deliveries. They’ll be enabled in a future release. Full payload schemas are in the API Reference tab.

Signature verification

Every delivery has three headers:

svix-id — unique delivery ID, stable across retries
svix-timestamp — Unix seconds at send time
svix-signature — HMAC signature(s). During secret rotation, multiple space-separated signatures are sent so subscribers have a verification window; any matching one proves authenticity.

Verify with the Svix SDK for your language:

import { Webhook } from "svix";

const wh = new Webhook(process.env.LYMO_WEBHOOK_SECRET!);
const payload = wh.verify(rawBody, {
  "svix-id": req.headers["svix-id"] as string,
  "svix-timestamp": req.headers["svix-timestamp"] as string,
  "svix-signature": req.headers["svix-signature"] as string,
});

Reject requests that fail verification. Pass the raw request body to verify — not a re-serialized JSON object.

Delivery semantics

Respond with any 2xx status to acknowledge; non-2xx responses or network failures trigger retries with exponential backoff.
The svix-id header is stable across retries — store received IDs and skip already-processed events to make your handler idempotent.
Retry schedule, timeout, and retention are handled by Svix. See Svix delivery documentation for specifics.

List and delete endpoints

# List registered endpoints
curl "$LYMO_BASE/v1/webhooks" -H "Authorization: Bearer $LYMO_KEY"

# Delete an endpoint
curl -X DELETE "$LYMO_BASE/v1/webhooks/ep_2abcXYZ12345" \
  -H "Authorization: Bearer $LYMO_KEY"

Endpoint IDs are Svix-issued and begin with ep_. Deleting an endpoint is immediate — in-flight deliveries still complete, but no new events are sent.

Get started

Concepts

Before you register: hostname allowlist

Register an endpoint

Event types

Signature verification

Delivery semantics

List and delete endpoints

​Before you register: hostname allowlist

​Register an endpoint

​Event types

​Signature verification

​Delivery semantics

​List and delete endpoints

Before you register: hostname allowlist

Register an endpoint

Event types

Signature verification

Delivery semantics

List and delete endpoints