Webhooks

Overview

Many MAVI API endpoints process tasks asynchronously. When you call an async endpoint, it immediately returns a task_id. Once processing completes, the API sends the results to your configured webhook URL via an HTTP POST request.

You must configure a webhook endpoint before using any async API. Without a webhook, you will not receive processing results.

Setup

Step 1: Open the Webhooks Settings

Go to the Webhooks Settings page in the MAVI Console.

Step 2: Add Your Webhook URL

Enter your callback URL. It must be:

A publicly accessible HTTPS endpoint
Able to accept POST requests with JSON body
Returns a 2xx status code on success

Step 3: Save

After saving, all async task results will be automatically delivered to your configured URL.

Webhook configuration is a one-time setup. Once configured, all async tasks across all API endpoints will send results to the same URL.

Async Endpoints That Require Webhooks

The following endpoints are asynchronous — they return a task_id on call and deliver results via webhook callback:

Endpoint	Description
`POST /video/extract-frames`	Extract frames from a video
`POST /video/clip`	Detect scene boundaries in a video
`POST /video/split`	Split a video into segments
`POST /video/edit`	AI-powered video editing
`POST /transcriptions/async-generate-audio`	Async audio transcription
`POST /transcriptions/async-generate-video`	Async video description
`POST /transcriptions/async-generate-speaker`	Async speaker diarization
`POST /transcriptions/async-generate-multi-speaker`	Multimodal speaker recognition
`POST /transcriptions/async-summary`	Async summary generation

How Async Tasks Work

Step 1: Configure webhook (one-time setup)
         → https://api-platform.memories.ai/webhooks

Step 2: Call an async endpoint
         → Returns { "data": { "task_id": "abc123" } }

Step 3: Wait for webhook callback
         → MAVI POSTs results to your webhook URL

Step 4: Match task_id to correlate request and response
         → callback body contains the same task_id

Example Flow

1. Call an async endpoint:

curl --request POST \
  --url https://mavi-backend.memories.ai/serve/api/v2/video/extract-frames \
  --header 'Authorization: sk-mavi-...' \
  --header 'Content-Type: application/json' \
  --data '{ "asset_id": "re_657739295220518912" }'

2. Receive immediate response with task_id:

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "1e8ae1075e054e8abb58e7598c53cbf1"
  },
  "success": true,
  "failed": false
}

3. Receive webhook callback when processing completes: Your webhook URL will receive a POST request with the results. The task_id in the callback matches the one from step 2.

Callback Payload Format

All webhook callbacks follow this general structure:

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    // Result data varies by endpoint — see each endpoint's
    // "Callback Response" section for details
  },
  "task_id": "1e8ae1075e054e8abb58e7598c53cbf1"
}

Field	Type	Description
`code`	integer	Status code. `200` indicates success.
`message`	string	Status message (e.g., `"SUCCESS"`).
`data`	object	The processing result. Structure varies by endpoint.
`task_id`	string	The task ID from the original async request. Use this to match callbacks to your requests.

Handling Webhook Callbacks

Here is an example webhook handler:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    payload = request.get_json()

    task_id = payload.get("task_id")
    code = payload.get("code")
    data = payload.get("data")

    if code == 200:
        print(f"Task {task_id} completed successfully")
        # Process the result data
    else:
        print(f"Task {task_id} failed with code {code}")

    return jsonify({"status": "ok"}), 200

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const { task_id, code, data } = req.body;

  if (code === 200) {
    console.log(`Task ${task_id} completed successfully`);
    // Process the result data
  } else {
    console.log(`Task ${task_id} failed with code ${code}`);
  }

  res.status(200).json({ status: 'ok' });
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Important Notes

Your webhook URL must be a publicly accessible HTTPS endpoint
The callback request method is always POST with a JSON body
Return a 2xx status code to acknowledge receipt; non-2xx responses may trigger retries
You can view callback history and debug failed deliveries at Webhooks Settings
Use the task_id field to correlate callbacks with your original requests

Get Started

Asset Management

Social Media Scraping

Audio File Transcription

Live Audio Transcription

Video Model APIs

Video Task APIs

Live Video Content Moderation

Live Video Understanding

Image Model APIs

Embeddings

Human ReID & Caption

Reference

Overview

Setup

Step 1: Open the Webhooks Settings

Step 2: Add Your Webhook URL

Step 3: Save

Async Endpoints That Require Webhooks

How Async Tasks Work

Example Flow

Callback Payload Format

Handling Webhook Callbacks

Important Notes

​Overview

​Setup

​Step 1: Open the Webhooks Settings

​Step 2: Add Your Webhook URL

​Step 3: Save

​Async Endpoints That Require Webhooks

​How Async Tasks Work

​Example Flow

​Callback Payload Format

​Handling Webhook Callbacks

​Important Notes

Overview

Setup

Step 1: Open the Webhooks Settings

Step 2: Add Your Webhook URL

Step 3: Save

Async Endpoints That Require Webhooks

How Async Tasks Work

Example Flow

Callback Payload Format

Handling Webhook Callbacks

Important Notes