Setup Steps

Navigate to Settings > Webhooks.
Enter your Webhook URL — this is the endpoint in your system that will receive event payloads.
(Optional) Enter a Webhook API Key — if provided, this key will be included in the Authorization header of each webhook request as Bearer YOUR_API_KEY. This allows your system to verify that incoming webhooks are from our service.
Toggle Enable Notifications to begin receiving webhook events.
Click Save. You're all set!

Your system should now begin receiving webhook events when relevant actions are triggered.

Per-Job Callback URLs (optional)

Add callback_url when creating a render to receive events for that job at that URL.
HTTPS only, 24h TTL; after expiry we fall back to your tenant webhook.
Manual re-submits of the same job reuse the original callback_url while it’s valid. Example (request body excerpt):

422 if invalid (non-HTTPS/private/too long).

Webhook Event Structure

Each webhook event is a POST request with a JSON payload sent to your registered callback URL. The structure looks like this:

Common Fields

Field	Type	Description
event_type	string	The type of event that occurred
created_at	string	ISO timestamp of when the event was triggered
data	data	Event-specific data payload

We mirror the event name in the header X-LipDub-Event: <event_type>

Supported Events

`VIDEO_RENDER_COMPLETE`

Triggered when a video render finishes successfully.

`RENDER_PROCESSING_FAILED`

Triggered when a render fails to complete due to a system or processing error.

If enabled for your account, you may also receive: PREPROCESSING_COMPLETE, TRAINING_COMPLETE, FILE_UPLOAD_COMPLETE/FAILED, VIDEO_VALIDATION_COMPLETE/FAILED, BEGIN_TRAINING_FAILURE (each includes a stage in data).

Additional events may be added in the future as more capabilities are exposed.

Handling Errors

If LipDub AI cannot successfully deliver a webhook (e.g., your server returns a 4XX or 5XX), we will retry delivery up to 3 times using an internal queue system (Amazon SQS FIFO).

After 3 failed attempts, the webhook will be moved to a Dead Letter Queue (DLQ) for inspection or manual replay by our support team.

To ensure reliable delivery:

Respond with a 200 OK status as quickly as possible (preferably within 5 seconds) — slow responses may be treated as failures
Avoid doing long processing directly in the webhook handler — offload to background jobs if needed.
Ensure idempotency, as webhook retries may result in duplicate payloads.
TTL & fallback: Per-job callback_url is valid for 24h. After expiry we automatically deliver to your tenant webhook.
If needed, contact support to request a replay of undelivered events from the DLQ.

Testing Your Integration

If you want to verify your endpoint:

Use a tool like RequestBin or Webhook.site to inspect payloads.
Trigger a test render in LipDub AI and confirm that your webhook URL receives the expected payload.

Security & Verification

Currently, webhook requests include:

A unique API key (used internally for now)
Your configured webhook URL
The payload data
If you set a Webhook API Key, we send Authorization: Bearer <WEBHOOK_API_KEY> (older tenants may see X-Api-Key).

In the future, we may support request signing (e.g., HMAC header verification) for enhanced security. Let us know if this is important for your integration.

Troubleshooting

Issue	Likely Cause	Suggested Fix
Not receiving any webhooks	Invalid or unreachable URL	Double-check your webhook URL in Settings > Webhooks
Receiving duplicate events	Retry behavior due to failed response	Ensure your handler returns `200 OK`
Unknown event type	Event not handled on your end	Add logic to gracefully ignore unknown events
No per-job callback received	TTL expired or invalid URL	Confirm job is less than 24h old; ensure HTTPS/public
Retry went to tenant webhook	Expected after TTL expiry	Re-submit with a fresh callback_url; otherwise route via tenant webhook

Contact Support

If you need help or want to report an issue with webhook delivery, please contact our team at

[email protected].