Skip to main content
POST
/
v2
/
endpoint
Add Webhook Endpoint
curl --request POST \
  --url https://api.jogg.ai/v2/endpoint \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "url": "https://your-domain.com/webhook",
  "status": "enabled",
  "events": [
    "generated_avatar_video_success",
    "generated_avatar_video_failed"
  ]
}
'
import requests

url = "https://api.jogg.ai/v2/endpoint"

payload = {
"url": "https://your-domain.com/webhook",
"status": "enabled",
"events": ["generated_avatar_video_success", "generated_avatar_video_failed"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://your-domain.com/webhook',
status: 'enabled',
events: ['generated_avatar_video_success', 'generated_avatar_video_failed']
})
};

fetch('https://api.jogg.ai/v2/endpoint', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.jogg.ai/v2/endpoint",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://your-domain.com/webhook',
'status' => 'enabled',
'events' => [
'generated_avatar_video_success',
'generated_avatar_video_failed'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.jogg.ai/v2/endpoint"

payload := strings.NewReader("{\n \"url\": \"https://your-domain.com/webhook\",\n \"status\": \"enabled\",\n \"events\": [\n \"generated_avatar_video_success\",\n \"generated_avatar_video_failed\"\n ]\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.jogg.ai/v2/endpoint")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://your-domain.com/webhook\",\n \"status\": \"enabled\",\n \"events\": [\n \"generated_avatar_video_success\",\n \"generated_avatar_video_failed\"\n ]\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.jogg.ai/v2/endpoint")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://your-domain.com/webhook\",\n \"status\": \"enabled\",\n \"events\": [\n \"generated_avatar_video_success\",\n \"generated_avatar_video_failed\"\n ]\n}"

response = http.request(request)
puts response.read_body
{
  "code": 0,
  "msg": "Success",
  "data": {
    "endpoint_id": "wh_123456789",
    "url": "https://your-domain.com/webhook",
    "secret": "whsec_abc123xyz",
    "status": "enabled",
    "events": [
      "generated_avatar_video_success",
      "generated_avatar_video_failed"
    ],
    "username": "johndoe",
    "created_at": 1732806631
  }
}
Create a new webhook endpoint to receive event notifications. You can specify which event types to subscribe to and configure the endpoint URL.
Limit: Each user can create up to 20 webhook endpoints.

Use Cases

  • Receive video generation completion notifications
  • Monitor task failure events
  • Track avatar creation status in real-time
  • Integrate with third-party systems

Important Notes

Webhook endpoints must be able to receive POST requests and return a 2xx status code within 5 seconds to confirm receipt.
Ensure your endpoint URL is a publicly accessible HTTPS address.

Available Event Types

Video Generation Events

EventDescriptionWhen Triggered
generated_video_successVideo generation succeededVideo is ready to download
generated_video_failedVideo generation failedAn error occurred during generation
generated_product_video_successProduct video generation succeededVideo is ready to download
generated_product_video_failedProduct video generation failedAn error occurred during generation
generated_avatar_video_successAvatar video generation succeededVideo is ready to download
generated_avatar_video_failedAvatar video generation failedAn error occurred during generation
generated_template_video_successTemplate video generation succeededVideo is ready to download
generated_template_video_failedTemplate video generation failedAn error occurred during generation
generated_translate_video_successVideo translation succeededTranslated video is ready
generated_translate_video_failedVideo translation failedAn error occurred during translation

Avatar Generation Events

EventDescriptionWhen Triggered
create_avatar_successAvatar creation succeededAvatar is ready to use
create_avatar_failedAvatar creation failedAn error occurred during avatar creation
generated_photo_avatar_successPhoto avatar creation succeededAvatar is ready to use
generated_photo_avatar_failedPhoto avatar creation failedAn error occurred during avatar creation
generated_product_avatar_successProduct avatar creation succeededAvatar is ready to use
generated_product_avatar_failedProduct avatar creation failedAn error occurred during avatar creation

AI Script Generation Events

EventDescriptionWhen Triggered
generated_script_successAI script generation succeededScripts are ready to use
generated_script_failedAI script generation failedAn error occurred during script generation

Image Generation Events

EventDescriptionWhen Triggered
generated_image_successImage generation succeededGenerated images are ready
generated_image_failedImage generation failedAn error occurred during image generation

Motion Generation Events

EventDescriptionWhen Triggered
generated_motion_successMotion generation succeededGenerated motion video is ready
generated_motion_failedMotion generation failedAn error occurred during motion generation
Use the List Webhook Events endpoint to get all available event types.

Webhook Signature Verification

Each webhook request includes a signature to verify the authenticity of the request source. Use the returned secret to verify the signature.

Example Request Headers

POST /webhook HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Webhook-Event: generated_avatar_video_success
X-Webhook-Signature: 7256c87be255861cbbe92f4a04a4500176b045a287f258e32e5b6c6b96d7f290
User-Agent: JoggAI-Webhook/2.0

Signature Verification Examples

Go

func VerifyWebhookSignature(payload []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(payload)
    expectedSignature := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(signature), []byte(expectedSignature))
}

Python

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

Best Practices

Quick Response

Return 200 status code within 5 seconds

Async Processing

Return immediately, process business logic in background

Idempotent Handling

Same event may be sent multiple times, ensure idempotency

Error Retry

System automatically retries failed webhooks

Authorizations

x-api-key
string
header
required

API key for authentication. Obtain your key from the JoggAI dashboard.

Body

application/json
url
string<uri>
required

Webhook endpoint URL that will receive POST requests

Example:

"https://your-domain.com/webhook"

status
enum<string>
required

Initial status of the webhook

Available options:
enabled,
disabled
Example:

"enabled"

events
string[]
required

List of event types to subscribe to

Example:
[
"generated_avatar_video_success",
"generated_avatar_video_failed"
]

Response

200 - application/json

Success

code
integer
required

Business status code:

  • 0 - Success
  • 10104 - Record not found
  • 10105 - Invalid API key
  • 18020 - Insufficient credit
  • 18025 - No permission to call APIs
  • 40000 - Parameter error
  • 50000 - System error
Example:

0

msg
string
required

Response message

Example:

"Success"

data
object