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

# Polling vs Webhooks: Choosing a Result Delivery Mode

> Choose between polling the status endpoint and receiving webhook callbacks for APIXO task results, with reliability trade-offs.

APIXO offers two ways to receive task results: polling (async mode) and webhooks (callback mode). This guide helps you choose the right approach and implement it effectively.

## Quick Comparison

| Aspect | Polling (Async) | Webhooks (Callback) |
| - | - | - |
| **Setup** | Simple | Requires public endpoint |
| **Real-time** | Near real-time | Instant |
| **API Calls** | Multiple per task | One per task |
| **Best For** | Development, client apps | Production servers |
| **Infrastructure** | None | HTTPS endpoint |

## When to Use Polling

**Choose polling when:**

* Building client-side applications
* Prototyping or testing
* You don't have a public server
* Processing low volume of tasks

### Basic Polling Implementation

```javascript theme={null}
async function pollForResult(model, taskId, apiKey) {
  const interval = 3000; // 3 seconds
  const maxAttempts = 60;
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.apixo.ai/api/v1/statusTask/${model}?taskId=${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    
    const { data } = await response.json();
    
    if (data.state === 'success') {
      return JSON.parse(data.resultJson).resultUrls;
    }
    if (data.state === 'failed') {
      throw new Error(data.failMsg);
    }
    
    await new Promise(r => setTimeout(r, interval));
  }
  
  throw new Error('Timeout');
}
```

### Exponential Backoff

For better efficiency, use exponential backoff:

```javascript theme={null}
async function pollWithBackoff(model, taskId, apiKey) {
  let interval = 3000; // Start at 3s
  const maxInterval = 30000; // Max 30s
  const maxTime = 300000; // 5 min timeout
  let elapsed = 0;
  
  while (elapsed < maxTime) {
    const response = await fetch(
      `https://api.apixo.ai/api/v1/statusTask/${model}?taskId=${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    
    const { data } = await response.json();
    
    if (data.state === 'success') {
      return JSON.parse(data.resultJson).resultUrls;
    }
    if (data.state === 'failed') {
      throw new Error(data.failMsg);
    }
    
    await new Promise(r => setTimeout(r, interval));
    elapsed += interval;
    interval = Math.min(interval * 1.5, maxInterval);
  }
  
  throw new Error('Timeout');
}
```

### Recommended Intervals by Model Type

| Model Type | Initial Wait | Poll Interval | Max Wait |
| - | - | - | - |
| Image (fast) | 5s | 3s | 2 min |
| Image (quality) | 10s | 5s | 3 min |
| Video | 60s | 15s | 10 min |
| Audio | 30s | 10s | 5 min |

## When to Use Webhooks

**Choose webhooks when:**

* Running a production server
* Processing high volume of tasks
* Need real-time notifications
* Want to minimize API calls

### Webhook Setup

**1. Create an endpoint:**

<Tabs>
  <Tab title="Express.js">
    ```javascript theme={null}
    const express = require('express');
    const app = express();

    app.use(express.json());

    app.post('/webhook/apixo', (req, res) => {
      const { taskId, state, resultJson, failCode, failMsg } = req.body.data;
      
      if (state === 'success') {
        const urls = JSON.parse(resultJson).resultUrls;
        console.log('Generated:', urls);
        // Process your images/videos
      } else if (state === 'failed') {
        console.error(`Task ${taskId} failed: ${failCode}`);
      }
      
      res.status(200).send('OK');
    });

    app.listen(3000);
    ```
  </Tab>

  <Tab title="FastAPI">
    ```python theme={null}
    from fastapi import FastAPI, Request
    import json

    app = FastAPI()

    @app.post('/webhook/apixo')
    async def handle_webhook(request: Request):
        body = await request.json()
        data = body['data']
        
        if data['state'] == 'success':
            urls = json.loads(data['resultJson'])['resultUrls']
            print(f"Generated: {urls}")
        elif data['state'] == 'failed':
            print(f"Task {data['taskId']} failed: {data['failCode']}")
        
        return {'status': 'ok'}
    ```
  </Tab>

  <Tab title="Next.js">
    ```typescript theme={null}
    // app/api/webhook/apixo/route.ts
    import { NextRequest, NextResponse } from 'next/server';

    export async function POST(request: NextRequest) {
      const body = await request.json();
      const { taskId, state, resultJson, failCode } = body.data;
      
      if (state === 'success') {
        const urls = JSON.parse(resultJson).resultUrls;
        console.log('Generated:', urls);
      } else if (state === 'failed') {
        console.error(`Task ${taskId} failed: ${failCode}`);
      }
      
      return NextResponse.json({ status: 'ok' });
    }
    ```
  </Tab>
</Tabs>

**2. Submit task with callback:**

```javascript theme={null}
const response = await fetch('https://api.apixo.ai/api/v1/generateTask/nano-banana', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    request_type: 'callback',
    callback_url: 'https://your-domain.com/webhook/apixo',
    input: {
      mode: 'text-to-image',
      prompt: 'A beautiful landscape',
    },
  }),
});
```

### Webhook Requirements

* Must be publicly accessible via HTTPS
* Must respond with HTTP 200 within 30 seconds
* Should handle duplicate deliveries (use `taskId` for idempotency)

### Retry Policy

If your webhook fails:

| Attempt | Delay |
| - | - |
| 1st retry | 30 seconds |
| 2nd retry | 2 minutes |
| 3rd retry | 10 minutes |

After 3 failed attempts, the webhook is abandoned. You can still query via the status endpoint.

## Hybrid Approach

For maximum reliability, combine both approaches:

```javascript theme={null}
class TaskManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.pendingTasks = new Map();
  }
  
  async submit(model, input, callbackUrl = null) {
    const response = await fetch(
      `https://api.apixo.ai/api/v1/generateTask/${model}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          request_type: callbackUrl ? 'callback' : 'async',
          callback_url: callbackUrl,
          input,
        }),
      }
    );
    
    const { data } = await response.json();
    
    if (!callbackUrl) {
      // Fallback to polling if no webhook
      return this.poll(model, data.taskId);
    }
    
    // Track task for webhook
    this.pendingTasks.set(data.taskId, { model, status: 'pending' });
    return data.taskId;
  }
  
  handleWebhook(body) {
    const { taskId, state, resultJson, failMsg } = body.data;
    
    if (state === 'success') {
      this.pendingTasks.delete(taskId);
      return JSON.parse(resultJson).resultUrls;
    }
    
    if (state === 'failed') {
      this.pendingTasks.delete(taskId);
      throw new Error(failMsg);
    }
  }
  
  async poll(model, taskId) {
    // Fallback polling implementation
    return pollWithBackoff(model, taskId, this.apiKey);
  }
}
```

## Local Development with ngrok

For testing webhooks locally:

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

# Start your local server
node server.js  # runs on port 3000

# Tunnel to local server
ngrok http 3000
# Returns: https://abc123.ngrok.io

# Use ngrok URL as callback_url
```

## Summary

| Scenario | Recommendation |
| - | - |
| Development / Testing | Polling |
| Client-side app | Polling |
| Production backend | Webhooks |
| High volume | Webhooks |
| Maximum reliability | Hybrid (webhooks + polling fallback) |

<Info>
  Start with polling for simplicity, then migrate to webhooks as your application scales.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.