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