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"
  ]
}
'

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

POST

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"
  ]
}
'

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

List Webhook Endpoints Update Webhook Endpoint

Documentation Index

​Use Cases

​Important Notes

​Available Event Types

​Video Generation Events

​Avatar Generation Events

​AI Script Generation Events

​Image Generation Events

​Motion Generation Events

​Webhook Signature Verification

​Example Request Headers

​Signature Verification Examples

​Go

​Python

​Node.js

​Best Practices

Quick Response

Async Processing

Idempotent Handling

Error Retry

Authorizations

Body

Response

Use Cases

Important Notes

Available Event Types

Video Generation Events

Avatar Generation Events

AI Script Generation Events

Image Generation Events

Motion Generation Events

Webhook Signature Verification

Example Request Headers

Signature Verification Examples

Go

Python

Node.js

Best Practices