Webhook Integration

Webhooks allow LipDub AI to send real-time notifications to your system when certain events occur, such as the completion or failure of a video render. This guide will walk you through setting up and handling webhooks effectively.

Setup Steps

Log in to your LipDub AI dashboard.

1. Navigate to Settings > Webhooks.
2. Enter your Webhook URL — this is the endpoint in your system that will receive event payloads.
3. (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.
4. Toggle Enable Notifications to begin receiving webhook events.
5. Click Save. You're all set!

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

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

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.

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.
• 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

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

Contact Support

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

[email protected].