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

# Webhooks Overview

> Get real-time notifications about your video generation and export jobs

## What are Webhooks?

Webhooks allow you to receive real-time notifications when your video generation or export jobs complete. Instead of polling the status endpoint repeatedly, Axeimmo will send an HTTP POST request to your specified URL when the job finishes.

## Benefits

<CardGroup cols={2}>
  <Card title="Real-time Updates" icon="bolt">
    Get notified immediately when jobs complete, no need to poll
  </Card>

  <Card title="Reduced API Calls" icon="chart-line-down">
    Save on rate limits by eliminating status polling
  </Card>

  <Card title="Better UX" icon="heart">
    Provide instant feedback to your users
  </Card>

  <Card title="Automation" icon="robot">
    Trigger downstream processes automatically
  </Card>
</CardGroup>

## How Webhooks Work

<Steps>
  <Step title="Configure Webhook URL">
    Include a `webhook_url` in your generation or export request
  </Step>

  <Step title="Job Processing">
    Axeimmo processes your video generation or export job
  </Step>

  <Step title="Webhook Delivery">
    When the job completes (success or failure), Axeimmo sends a POST request to your URL
  </Step>

  <Step title="Acknowledgment">
    Your endpoint should respond with a 200 status code to confirm receipt
  </Step>
</Steps>

## Webhook Payload

### Successful Generation

```json theme={null}
{
  "job_id": "run_01234567890abcdef",
  "status": "completed",
  "result": {
    "video_id": "video_abcdef1234567890",
    "thumbnail_url": "https://cdn.axeimmo.com/thumbnails/video_123.jpg",
    "cost": 5,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### Failed Generation

```json theme={null}
{
  "job_id": "run_01234567890abcdef",
  "status": "failed",
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete video generation"
  }
}
```

### Successful Export

```json theme={null}
{
  "job_id": "run_fedcba0987654321",
  "status": "completed", 
  "result": {
    "video_url": "https://cdn.axeimmo.com/exports/video_456.mp4",
    "thumbnail_url": "https://cdn.axeimmo.com/thumbnails/video_456.jpg",
    "cost": 3,
    "created_at": "2024-01-15T10:35:00Z"
  }
}
```

## Setting Up Webhooks

### 1. Create an Endpoint

Your webhook endpoint should:

* Accept POST requests
* Respond with 200 status code
* Process the payload asynchronously if needed

<CodeGroup>
  ```javascript Node.js/Express theme={null}
  app.post('/webhook/axeimmo', express.json(), (req, res) => {
    const { job_id, status, result, error } = req.body;
    
    console.log(`Webhook received for job ${job_id}: ${status}`);
    
    if (status === 'completed') {
      // Handle successful completion
      console.log('Video ready:', result.video_id);
      
      // Update your database
      updateJobStatus(job_id, 'completed', result);
      
      // Notify user
      notifyUser(job_id, result);
      
    } else if (status === 'failed') {
      // Handle failure
      console.error('Job failed:', error);
      
      // Update your database
      updateJobStatus(job_id, 'failed', null, error);
      
      // Notify user of failure
      notifyUserOfFailure(job_id, error);
    }
    
    // Always respond with 200
    res.status(200).send('OK');
  });
  ```

  ```python Python/Flask theme={null}
  from flask import Flask, request, jsonify

  @app.route('/webhook/axeimmo', methods=['POST'])
  def axeimmo_webhook():
      data = request.get_json()
      
      job_id = data.get('job_id')
      status = data.get('status')
      result = data.get('result')
      error = data.get('error')
      
      print(f"Webhook received for job {job_id}: {status}")
      
      if status == 'completed':
          # Handle successful completion
          print(f"Video ready: {result.get('video_id')}")
          
          # Update your database
          update_job_status(job_id, 'completed', result)
          
          # Notify user
          notify_user(job_id, result)
          
      elif status == 'failed':
          # Handle failure  
          print(f"Job failed: {error}")
          
          # Update your database
          update_job_status(job_id, 'failed', None, error)
          
          # Notify user of failure
          notify_user_of_failure(job_id, error)
      
      # Always respond with 200
      return jsonify({'status': 'ok'}), 200
  ```

  ```php PHP theme={null}
  <?php
  // webhook.php

  // Get the JSON payload
  $payload = json_decode(file_get_contents('php://input'), true);

  $jobId = $payload['job_id'];
  $status = $payload['status'];
  $result = $payload['result'] ?? null;
  $error = $payload['error'] ?? null;

  error_log("Webhook received for job $jobId: $status");

  if ($status === 'completed') {
      // Handle successful completion
      $videoId = $result['video_id'];
      error_log("Video ready: $videoId");
      
      // Update your database
      updateJobStatus($jobId, 'completed', $result);
      
      // Notify user
      notifyUser($jobId, $result);
      
  } elseif ($status === 'failed') {
      // Handle failure
      error_log("Job failed: " . $error['message']);
      
      // Update your database  
      updateJobStatus($jobId, 'failed', null, $error);
      
      // Notify user of failure
      notifyUserOfFailure($jobId, $error);
  }

  // Always respond with 200
  http_response_code(200);
  echo 'OK';
  ?>
  ```
</CodeGroup>

### 2. Use in API Calls

Include your webhook URL when starting jobs:

<CodeGroup>
  ```javascript Generation theme={null}
  const response = await fetch('https://app.axeimmo.com/api/public/v1/generation/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Create a video about space exploration",
      voice_id: "en-US-JennyNeural",
      webhook_url: "https://your-app.com/webhook/axeimmo"
    })
  });
  ```

  ```javascript Export theme={null}
  const response = await fetch('https://app.axeimmo.com/api/public/v1/export/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_id: "video_123",
      format: "vertical",
      webhook_url: "https://your-app.com/webhook/axeimmo"
    })
  });
  ```
</CodeGroup>

## Security Considerations

### 1. Validate Requests

Verify that webhook requests are coming from Axeimmo:

```javascript theme={null}
// Check User-Agent header
const userAgent = req.headers['user-agent'];
if (!userAgent || !userAgent.includes('Axeimmo-API')) {
  return res.status(401).send('Unauthorized');
}

// Check for Axeimmo webhook header
const isAxeimmoWebhook = req.headers['x-axeimmo-webhook'];
if (isAxeimmoWebhook !== 'true') {
  return res.status(401).send('Unauthorized');
}
```

### 2. Use HTTPS

Always use HTTPS URLs for your webhook endpoints to ensure data is encrypted in transit.

### 3. Implement Idempotency

Handle duplicate webhook deliveries gracefully:

```javascript theme={null}
const processedJobs = new Set();

app.post('/webhook/axeimmo', (req, res) => {
  const { job_id } = req.body;
  
  // Check if we've already processed this job
  if (processedJobs.has(job_id)) {
    console.log(`Duplicate webhook for job ${job_id}, ignoring`);
    return res.status(200).send('OK');
  }
  
  // Process the webhook
  processWebhook(req.body);
  
  // Mark as processed
  processedJobs.add(job_id);
  
  res.status(200).send('OK');
});
```

## Retry Behavior

Axeimmo will retry webhook deliveries if your endpoint:

* Returns a non-2xx status code
* Times out (after 10 seconds)
* Is unreachable

**Retry Schedule:**

* 1st retry: After 1 second
* 2nd retry: After 2 seconds
* 3rd retry: After 4 seconds
* **Maximum**: 3 retry attempts

<Warning>
  If all retries fail, the webhook will be discarded. Ensure your endpoint is reliable and responds quickly.
</Warning>

## Testing Webhooks

### 1. Use ngrok for Local Development

```bash theme={null}
# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

# Use the HTTPS URL in your webhook_url
# https://abc123.ngrok.io/webhook/axeimmo
```

### 2. Webhook Testing Tools

* **RequestBin**: Create temporary endpoints to inspect payloads
* **Webhook.site**: Test and debug webhook deliveries
* **Postman**: Mock webhook requests for testing

### 3. Test Endpoint

Create a simple test endpoint to verify webhook delivery:

```javascript theme={null}
app.post('/webhook/test', (req, res) => {
  console.log('Webhook Headers:', req.headers);
  console.log('Webhook Body:', JSON.stringify(req.body, null, 2));
  res.status(200).send('Webhook received successfully');
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="Response Time">
    * Respond with 200 status as quickly as possible
    * Process heavy operations asynchronously
    * Use queues for complex workflows
  </Accordion>

  <Accordion title="Error Handling">
    * Log all webhook deliveries for debugging
    * Handle malformed payloads gracefully
    * Implement monitoring and alerting
  </Accordion>

  <Accordion title="Scalability">
    * Use load balancers for high-volume webhooks
    * Implement rate limiting on your endpoint
    * Consider using message queues for processing
  </Accordion>
</AccordionGroup>

## Common Issues

| Issue                 | Cause                       | Solution                            |
| --------------------- | --------------------------- | ----------------------------------- |
| Webhooks not received | Endpoint unreachable        | Check URL and firewall settings     |
| Duplicate processing  | No idempotency check        | Implement job ID tracking           |
| Slow processing       | Heavy operations in handler | Move to background jobs             |
| Missing webhooks      | Endpoint returning errors   | Fix endpoint logic and status codes |

<Tip>
  Always test your webhook endpoints thoroughly before using them in production.
</Tip>