Add Webhook Endpoint

Create a new webhook endpoint to receive event notifications. You can specify which events to subscribe to and configure the endpoint URL.

POST /v2/endpoint

Add Webhook Endpoint

cURL

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

200

{
  "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

Event	Description	When Triggered
generated_video_success	Video generation succeeded	Video is ready to download
generated_video_failed	Video generation failed	An error occurred during generation
generated_product_video_success	Product video generation succeeded	Video is ready to download
generated_product_video_failed	Product video generation failed	An error occurred during generation
generated_avatar_video_success	Avatar video generation succeeded	Video is ready to download
generated_avatar_video_failed	Avatar video generation failed	An error occurred during generation
generated_template_video_success	Template video generation succeeded	Video is ready to download
generated_template_video_failed	Template video generation failed	An error occurred during generation
generated_translate_video_success	Video translation succeeded	Translated video is ready
generated_translate_video_failed	Video translation failed	An error occurred during translation

Avatar Generation Events

Event	Description	When Triggered
create_avatar_success	Avatar creation succeeded	Avatar is ready to use
create_avatar_failed	Avatar creation failed	An error occurred during avatar creation
generated_photo_avatar_success	Photo avatar creation succeeded	Avatar is ready to use
generated_photo_avatar_failed	Photo avatar creation failed	An error occurred during avatar creation
generated_product_avatar_success	Product avatar creation succeeded	Avatar is ready to use
generated_product_avatar_failed	Product avatar creation failed	An error occurred during avatar creation

AI Script Generation Events

Event	Description	When Triggered
generated_script_success	AI script generation succeeded	Scripts are ready to use
generated_script_failed	AI script generation failed	An error occurred during script generation

Image Generation Events

Event	Description	When Triggered
generated_image_success	Image generation succeeded	Generated images are ready
generated_image_failed	Image generation failed	An error occurred during image generation

Motion Generation Events

Event	Description	When Triggered
generated_motion_success	Motion generation succeeded	Generated motion video is ready
generated_motion_failed	Motion generation failed	An 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

Show child attributes