> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jogg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.


Create a new webhook endpoint to receive event notifications.

You can specify which event types to subscribe to and configure the endpoint URL.

<Info>
  **Limit**: Each user can create up to **20** webhook endpoints.
</Info>

## 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

<Note>
  Webhook endpoints must be able to receive POST requests and return a 2xx status code within **5 seconds** to confirm receipt.
</Note>

<Warning>
  Ensure your endpoint URL is a publicly accessible **HTTPS** address.
</Warning>

## 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 |

<Tip>
  Use the [List Webhook Events](/api-reference/v2/Webhook/ListWebhookEvents) endpoint to get all available event types.
</Tip>

## 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

```http theme={null}
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

```go theme={null}
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

```python theme={null}
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

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Quick Response" icon="bolt">
    Return 200 status code within 5 seconds
  </Card>

  <Card title="Async Processing" icon="clock">
    Return immediately, process business logic in background
  </Card>

  <Card title="Idempotent Handling" icon="check-double">
    Same event may be sent multiple times, ensure idempotency
  </Card>

  <Card title="Error Retry" icon="rotate">
    System automatically retries failed webhooks
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v2/endpoint
openapi: 3.0.1
info:
  title: JoggAI OpenAPI v2
  description: >
    JoggAI OpenAPI v2 provides a comprehensive suite of endpoints for creating
    and managing AI-powered video content.


    ## Authentication

    All API requests require authentication using an API key provided in the
    `x-api-key` header.


    ## Base URL

    Production: https://api.jogg.ai/v2


    ## Rate Limiting

    API calls are subject to rate limiting based on your subscription plan.


    ## Error Handling

    All endpoints return standard HTTP status codes along with detailed error
    messages in the response body.
  version: 2.0.0
  license:
    name: MIT
servers:
  - url: https://api.jogg.ai
    description: Production server
security:
  - apiKeyAuth: []
tags:
  - name: Video
    description: Video creation and management operations
  - name: Avatar
    description: Avatar management and creation operations
  - name: Voice
    description: Voice and timbre management operations
  - name: Asset
    description: Asset management including music, scripts, and uploads
  - name: Template
    description: Template management operations
  - name: Product
    description: Product management operations
  - name: User
    description: User account operations
  - name: Webhook
    description: Webhook endpoint management for event notifications
paths:
  /v2/endpoint:
    post:
      tags:
        - Webhook
      summary: Add Webhook Endpoint
      description: >
        Create a new webhook endpoint to receive event notifications.

        You can specify which events to subscribe to and configure the endpoint
        URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - status
                - events
              properties:
                url:
                  type: string
                  format: uri
                  description: Webhook endpoint URL that will receive POST requests
                  example: https://your-domain.com/webhook
                status:
                  type: string
                  description: Initial status of the webhook
                  enum:
                    - enabled
                    - disabled
                  example: enabled
                events:
                  type: array
                  description: List of event types to subscribe to
                  items:
                    type: string
                  example:
                    - generated_avatar_video_success
                    - generated_avatar_video_failed
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WebhookEndpoint'
components:
  schemas:
    BaseResponse:
      type: object
      required:
        - code
        - msg
      properties:
        code:
          type: integer
          description: |
            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:
          type: string
          description: Response message
          example: Success
    WebhookEndpoint:
      type: object
      properties:
        endpoint_id:
          type: string
          description: Unique webhook endpoint identifier
          example: wh_123456789
        url:
          type: string
          format: uri
          description: Webhook endpoint URL
          example: https://your-domain.com/webhook
        secret:
          type: string
          description: Secret key for verifying webhook signatures
          example: whsec_abc123xyz
        status:
          type: string
          description: Webhook status
          enum:
            - enabled
            - disabled
          example: enabled
        events:
          type: array
          description: Subscribed event types
          items:
            type: string
          example:
            - generated_avatar_video_success
            - generated_avatar_video_failed
        username:
          type: string
          description: Username of the webhook owner
          example: johndoe
        created_at:
          type: integer
          description: Creation timestamp (Unix timestamp)
          example: 1732806631
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Obtain your key from the JoggAI dashboard.

````