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

# List Webhook Events

> Get a list of all available webhook event types that you can subscribe to.
Each event type represents a specific action or status change in the system.


Get a list of all available webhook event types that you can subscribe to.

Each event type represents a specific action or status change in the system.

## Use Cases

* View all available event types
* Select events to subscribe to
* Understand event naming conventions

## Response Example

```json theme={null}
{
  "rid": "",
  "code": 0,
  "msg": "success",
  "data": {
    "events": [
      "generated_video_success",
      "generated_video_failed",
      "create_avatar_success",
      "create_avatar_failed",
      "generated_image_success",
      "generated_image_failed",
      "generated_motion_success",
      "generated_motion_failed",
      "generated_product_video_success",
      "generated_product_video_failed",
      "generated_avatar_video_success",
      "generated_avatar_video_failed",
      "generated_template_video_success",
      "generated_template_video_failed",
      "generated_translate_video_success",
      "generated_translate_video_failed",
      "generated_photo_avatar_success",
      "generated_photo_avatar_failed",
      "generated_product_avatar_success",
      "generated_product_avatar_failed",
      "generated_script_success",
      "generated_script_failed"
    ]
  }
}
```

## Available Event Types

### Video Generation Events

| Event Type                          | Description                         |
| ----------------------------------- | ----------------------------------- |
| `generated_video_success`           | Video generation succeeded          |
| `generated_video_failed`            | Video generation failed             |
| `generated_product_video_success`   | Product video generation succeeded  |
| `generated_product_video_failed`    | Product video generation failed     |
| `generated_avatar_video_success`    | Avatar video generation succeeded   |
| `generated_avatar_video_failed`     | Avatar video generation failed      |
| `generated_template_video_success`  | Template video generation succeeded |
| `generated_template_video_failed`   | Template video generation failed    |
| `generated_translate_video_success` | Video translation succeeded         |
| `generated_translate_video_failed`  | Video translation failed            |

### Avatar Generation Events

| Event Type                         | Description                       |
| ---------------------------------- | --------------------------------- |
| `create_avatar_success`            | Avatar creation succeeded         |
| `create_avatar_failed`             | Avatar creation failed            |
| `generated_photo_avatar_success`   | Photo avatar creation succeeded   |
| `generated_photo_avatar_failed`    | Photo avatar creation failed      |
| `generated_product_avatar_success` | Product avatar creation succeeded |
| `generated_product_avatar_failed`  | Product avatar creation failed    |

### AI Script Generation Events

| Event Type                 | Description                    |
| -------------------------- | ------------------------------ |
| `generated_script_success` | AI script generation succeeded |
| `generated_script_failed`  | AI script generation failed    |

### Image Generation Events

| Event Type                | Description                |
| ------------------------- | -------------------------- |
| `generated_image_success` | Image generation succeeded |
| `generated_image_failed`  | Image generation failed    |

### Motion Generation Events

| Event Type                 | Description                 |
| -------------------------- | --------------------------- |
| `generated_motion_success` | Motion generation succeeded |
| `generated_motion_failed`  | Motion generation failed    |

<Tip>
  We recommend subscribing to at least `*_success` and `*_failed` events to stay informed about task completion status.
</Tip>

## Webhook Payload Examples

When an event is triggered, your endpoint will receive a JSON payload similar to the following:

### Video Generation Success Event

```json theme={null}
{
  "event_id": "evt_123456789",
  "event": "generated_avatar_video_success",
  "timestamp": 1732806631,
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/video.mp4",
    "cover_url": "https://res.jogg.ai/cover.jpg",
    "duration": 30
  }
}
```

### Avatar Generation Success Event

```json theme={null}
{
  "event_id": "evt_987654321",
  "event": "generated_photo_avatar_success",
  "timestamp": 1732806631,
  "data": {
    "avatar_id": 12345,
    "status": "completed",
    "preview_url": "https://res.jogg.ai/avatar-preview.mp4"
  }
}
```

### Script Generation Success Event

```json theme={null}
{
  "event": "generated_script_success",
  "timestamp": 1732806631,
  "data": {
    "task_id": "task_123456",
    "status": "completed",
    "scripts": [
      {
        "script_style": "Storytime",
        "script_paragraphs": "Your generated script content..."
      }
    ]
  }
}
```

### Image Generation Success Event

```json theme={null}
{
  "event": "generated_image_success",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_123456",
    "photo_urls": [
      "https://res.jogg.ai/image1.jpg",
      "https://res.jogg.ai/image2.jpg"
    ]
  }
}
```

### Image Generation Failed Event

```json theme={null}
{
  "event": "generated_image_failed",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_123456",
    "error": "Image generation failed due to invalid parameters"
  }
}
```

### Motion Generation Success Event

```json theme={null}
{
  "event": "generated_motion_success",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_123456",
    "motion_url": "https://res.jogg.ai/motion.mp4",
    "photo_url": "https://res.jogg.ai/photo.jpg"
  }
}
```

### Motion Generation Failed Event

```json theme={null}
{
  "event": "generated_motion_failed",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_123456",
    "error": "Motion generation failed due to processing error"
  }
}
```

## Best Practices

<Info>
  * **Use idempotent processing**: The same event may be sent multiple times, ensure your logic handles this
  * **Implement retry logic**: The system will retry sending webhooks if processing fails
  * **Respond quickly**: Return a 2xx status code within 5 seconds to avoid timeouts
  * **Process asynchronously**: Return 200 immediately after receiving the event, then process business logic asynchronously
  * **Verify signatures**: Use the webhook secret to verify request authenticity
</Info>

## Event Naming Convention

Most events follow the `generated_{resource}_{status}` or `create_{resource}_{status}` naming pattern:

* `{resource}`: Resource type (e.g., `avatar_video`, `product_avatar`, `script`, `avatar`)
* `{status}`: Status (`success` or `failed`)

**Note:** Some legacy events use simpler naming (e.g., `generated_video_success`, `create_avatar_success`).


## OpenAPI

````yaml GET /v2/events
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/events:
    get:
      tags:
        - Webhook
      summary: List Webhook Events
      description: >
        Get a list of all available webhook event types that you can subscribe
        to.

        Each event type represents a specific action or status change in the
        system.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          events:
                            type: array
                            description: List of available event types
                            items:
                              type: string
                            example:
                              - generated_video_success
                              - generated_video_failed
                              - create_avatar_success
                              - create_avatar_failed
                              - generated_product_video_success
                              - generated_product_video_failed
                              - generated_avatar_video_success
                              - generated_avatar_video_failed
                              - generated_template_video_success
                              - generated_template_video_failed
                              - generated_translate_video_success
                              - generated_translate_video_failed
                              - generated_photo_avatar_success
                              - generated_photo_avatar_failed
                              - generated_product_avatar_success
                              - generated_product_avatar_failed
                              - generated_script_success
                              - generated_script_failed
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
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Obtain your key from the JoggAI dashboard.

````