The Vionlabs Webhooks feature allows your systems to automatically receive notifications from Vionlabs whenever asset processing is complete.
Instead of continuously polling our APIs for updates, webhooks push relevant events directly to your own backend, enabling real-time automation and smarter data workflows.

This guide explains how webhooks work, how to configure your receiving service, and what information you can expect in each payload.

1. What Is a Webhook?

A webhook is an automatic message sent from the Vionlabs backend to your system as soon as processing for a given asset or task has finished. You can think of it as a push notification for your infrastructure — lightweight, event-driven, and immediate.

A webhook can include:

Processing state – confirmation that a given processing job has completed

Optional results – structured metadata such as:

product (the processed product, e.g., Mood, Genre, AdBreaks)

version (the model version used)

inventory_id (your internal reference to the asset)

type (asset type: standalone, episodic, etc.)

timestamp (time the event occurred)

💡 Webhooks do not contain the full processing results or success/failure status.
To retrieve full analytics and output data, use the Result API after receiving a webhook notification.

2. How Webhook Communication Works

Webhook communication is based on a simple two-way configuration process between your infrastructure and the Vionlabs backend.

Step 1 – Customer Setup

You deploy a webhook receiver service on your side — this is an endpoint capable of accepting HTTP requests (e.g., POST or PUT) from Vionlabs.
It acts as your listener, waiting for incoming event messages.

You’ll then provide Vionlabs with the following configuration details:

Service URL: e.g., https://your-domain.com/webhooks/vionlabs

HTTP Method: one of POST, PUT, or GET (recommended: POST)

Optional Query Parameters: e.g., ?auth-key=abc123

Optional Headers: e.g., x-api-key: your-secret-key

Maximum Parallel Connections: define concurrency for event delivery

📎 Reference Implementation:
You can find a sample webhook receiver implementation on GitLab:
Vionlabs Customer Notifier Hook
 

Step 2 – Vionlabs Setup

After you share your webhook endpoint details, the Vionlabs team will configure your webhook on our backend to ensure proper connectivity.

We will:

• Register your service connection details
• Define which event types you should receive (e.g., processing_complete, asset_ready)
• Perform connection tests to verify successful event delivery

Once this setup is complete, Vionlabs will begin sending webhook notifications automatically for your configured events.

3. Typical Event Flow

Here’s how webhook communication works during normal operation:

• You ingest an asset and trigger processing (manually via Task API or automatically via Catalog API).
• Processing completes on Vionlabs infrastructure.
• Webhook notification is sent to your receiver endpoint.
• Your system handles the payload, updates internal state, and optionally calls the Result API to fetch detailed data.

Vionlabs confirms delivery via standard HTTP response (2xx status).

This model enables event-driven integration, where your downstream services can automatically act upon the completion of any processing job — for example, to update dashboards, refresh thumbnails, or move assets to a new workflow stage.

4. Example Payload

Below is an example of what a webhook payload might look like:

{
  "event": "processing_complete",
  "product": "mood",
  "version": "v2.3",
  "inventory_id": "MOVIE-1234",
  "type": "standalone",
  "timestamp": "2025-12-12T09:42:17Z" 
} 

Your receiver should validate the structure, store the event, and use the inventory_id to query results via the Result API if needed.

5. Implementation Recommendations

To ensure your webhook integration is secure and reliable:

• 🔐 Secure your endpoint: Use HTTPS and include authentication tokens or keys in headers.
• 🔄 Implement retries: Webhooks can occasionally fail due to network issues; add retry logic with exponential backoff.
• 🧩 Log incoming requests: Keep a record of received events for debugging or verification.
• 🧠 Respond quickly: Return a 200-series HTTP code immediately upon receipt; long processing in the webhook handler can delay future deliveries.
• 🧯 Idempotency: Design your receiver to safely handle duplicate events.

6. Testing Your Webhook

After setup, the Vionlabs team performs an initial test to ensure your endpoint is reachable and correctly processes the webhook event.

You can also test manually using tools like Postman or curl:

curl -X POST https://your-domain.com/webhooks/vionlabs \
  -H "Content-Type: application/json" \
  -d '{"event": "processing_complete", "inventory_id": "TEST-001"}' 

A 200 OK response confirms that your webhook is configured correctly.

7. Troubleshooting

If issues persist, contact Vionlabs Support with your webhook endpoint URL and timestamps of missed events for verification.

8. Summary

Webhooks are an essential integration feature of the Vionlabs platform.
They enable real-time event notifications to your own systems, helping you automate processing pipelines, trigger downstream tasks, and maintain synchronization between your infrastructure and Vionlabs AI workflows.

By setting up your webhook endpoint correctly and following best practices for authentication and reliability, you can achieve efficient, event-driven processing without constant API polling — a scalable and modern approach to integrating Vionlabs intelligence into your ecosystem.