Skip to main content

Overview

Webhooks allow you to receive real-time notifications when your API requests complete processing. Instead of polling the fetch endpoint repeatedly, ModelsLab will send the results directly to your server.
Best for: Long-running operations like video generation, model training, and batch image processing where you don’t want to keep polling for results.

How Webhooks Work

1

Include Webhook URL

Add the webhook parameter to your API request with your endpoint URL.
2

Request Processing

ModelsLab processes your request asynchronously.
3

Webhook Delivery

When complete, ModelsLab sends a POST request to your webhook URL with the results.

Using Webhooks

Add the webhook parameter to any API request that supports async processing:

Webhook Payload

When your request completes, ModelsLab sends a POST request to your webhook URL with this payload:

Success Payload

Failure Payload

Workflow Webhook Payload

For Workflows API, the payload structure includes additional workflow information:

Setting Up Your Webhook Endpoint

Create an endpoint on your server to receive webhook notifications:

Webhook Requirements

HTTPS Required

Your webhook URL must use HTTPS for security.

Respond Quickly

Return a 2xx status code within 30 seconds to acknowledge receipt.

Handle Duplicates

Webhooks may be sent multiple times. Use id or track_id for idempotency.

Public Endpoint

Your webhook endpoint must be publicly accessible.

The track_id Parameter

Use track_id to correlate webhook responses with your internal records:

Retry Policy

If your webhook endpoint is unreachable or returns a non-2xx status:
  • Workflow webhooks: Retried up to 3 times with exponential backoff
  • Generation webhooks: Best-effort delivery, use fetch endpoint as fallback
Always implement the fetch endpoint as a fallback. If you don’t receive a webhook within the expected time, poll the fetch endpoint.

Testing Webhooks Locally

Use a tunneling service to test webhooks during development:

Using ngrok

Using localtunnel

Best Practices

Return a 200 or 202 status code immediately to acknowledge receipt. Do heavy processing asynchronously.
Store the id or track_id and check before processing to handle duplicate deliveries.
Log all incoming webhook payloads for debugging and audit purposes.
For production systems, push webhook data to a queue (Redis, SQS, etc.) and process asynchronously.
Monitor your webhook endpoint for failures and response times.

Endpoints Supporting Webhooks

The webhook parameter is supported by these API endpoints:

Troubleshooting

  1. Verify your URL is publicly accessible (test with curl from outside your network)
  2. Check your server logs for incoming requests
  3. Ensure your endpoint returns 2xx within 30 seconds
  4. Use the fetch endpoint to check if the request completed
This is expected behavior for reliability. Implement idempotency using the request id or your track_id.
If your processing takes too long:
  1. Return 200 immediately
  2. Process the webhook payload asynchronously
  3. Use a message queue for heavy processing

Next Steps

Video API

Generate videos with webhook notifications

Workflows API

Create complex pipelines with webhooks