Webhook Callbacks

Instead of polling the status endpoint, you can provide a callback URL when submitting tasks to receive automatic notifications when generation completes.

How It Works

Submit with callback URL: Include a callback_url in your task submission
Receive notification: When the task completes (success or failure), PoYo AI sends a POST request to your URL
Process result: Your server receives the complete task data including generated files

Callback Request

When a task completes, PoYo AI sends a POST request to your callback URL. The callback body uses the same task data shape as the status endpoint, without the outer code and data wrapper.

Request Headers

Content-Type: application/json
X-Webhook-Timestamp: 1783680000
X-Webhook-Signature: base64_hmac_sha256_signature

Request Body

{
  "task_id": "task-unified-1757165031-uyujaw3d",
  "status": "finished",
  "files": [
    {
      "file_url": "https://storage.poyo.ai/generated/image-abc123.jpg",
      "file_type": "image"
    }
  ],
  "created_time": "2025-11-12T10:30:00",
  "error_message": null
}

Failed Task Callback

{
  "task_id": "task-unified-1757165031-uyujaw3d",
  "status": "failed",
  "files": [],
  "created_time": "2025-11-12T10:30:00",
  "error_message": "The prompt violates our content policy"
}

Signature Verification

PoYo signs every webhook request with HMAC-SHA256. Existing receivers can ignore these headers, but production systems should verify them. Get your webhook HMAC key:

GET /api/api-keys/webhook-secret

Rotate your webhook HMAC key:

POST /api/api-keys/webhook-secret/rotate

Signature rule:

base64(HMAC-SHA256(task_id + "." + timestamp, webhook_hmac_key))

Where:

task_id is the top-level task_id in the callback body
timestamp is the value of X-Webhook-Timestamp
webhook_hmac_key is returned by GET /api/api-keys/webhook-secret

Python Verification

import base64
import hashlib
import hmac
import time


def verify_poyo_webhook(payload, headers, webhook_hmac_key):
    task_id = payload.get("task_id")
    timestamp = headers.get("X-Webhook-Timestamp")
    received_signature = headers.get("X-Webhook-Signature")

    if not task_id or not timestamp or not received_signature:
        return False

    if abs(int(time.time()) - int(timestamp)) > 300:
        return False

    expected_signature = base64.b64encode(
        hmac.new(
            webhook_hmac_key.encode("utf-8"),
            f"{task_id}.{timestamp}".encode("utf-8"),
            hashlib.sha256,
        ).digest()
    ).decode("utf-8")

    return hmac.compare_digest(expected_signature, received_signature)

Node.js Verification

const crypto = require("crypto");

function verifyPoyoWebhook(payload, headers, webhookHmacKey) {
  const taskId = payload.task_id;
  const timestamp = headers["x-webhook-timestamp"];
  const receivedSignature = headers["x-webhook-signature"];

  if (!taskId || !timestamp || !receivedSignature) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) return false;

  const expectedSignature = crypto
    .createHmac("sha256", webhookHmacKey)
    .update(`${taskId}.${timestamp}`)
    .digest("base64");

  if (expectedSignature.length !== receivedSignature.length) return false;

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  );
}

Requirements

Your callback endpoint must meet the following requirements:

HTTPS only: Must use HTTPS protocol (HTTP not supported)
Maximum URL length: 2048 characters
Response timeout: Must respond within 30 seconds
Success response: Should return HTTP 200-299 status code
No internal IPs: Cannot use private/internal IP addresses (e.g., 192.168.x.x, 10.x.x.x)
Public accessibility: Must be publicly accessible from the internet

Retry Policy

If your callback endpoint fails to respond or returns an error:

Retry attempts: Up to 5 automatic retries
Retry delays: Exponential backoff, starting at about 60 seconds and capped at 10 minutes
Final failure: After all retry attempts fail, no further retries are made

If all retry attempts fail, you can still retrieve the results by polling the status endpoint.

Example Implementation

Python (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/generation-complete', methods=['POST'])
def handle_generation_complete():
    # Parse the callback payload
    data = request.json
    task_id = data.get('task_id')
    status = data.get('status')

    if status == 'finished':
        # Task completed successfully
        files = data.get('files', [])
        for file in files:
            print(f"Generated file: {file['file_url']}")
            # Download and process the file
            # save_file(file['file_url'])

    elif status == 'failed':
        # Task failed
        error = data.get('error_message')
        print(f"Task {task_id} failed: {error}")
        # Handle the failure

    # Return 200 to acknowledge receipt
    return jsonify({"received": True}), 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=443, ssl_context='adhoc')

Node.js (Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/generation-complete', (req, res) => {
  const { task_id, status, files, error_message } = req.body;

  if (status === 'finished') {
    // Task completed successfully
    console.log(`Task ${task_id} completed`);
    files.forEach(file => {
      console.log(`Generated file: ${file.file_url}`);
      // Download and process the file
    });
  } else if (status === 'failed') {
    // Task failed
    console.log(`Task ${task_id} failed: ${error_message}`);
    // Handle the failure
  }

  // Return 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem')
};

https.createServer(options, app).listen(443, () => {
  console.log('Webhook server listening on port 443');
});

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type TaskData struct {
    TaskID       string      `json:"task_id"`
    Status       string      `json:"status"`
    Files        []MediaFile `json:"files"`
    CreatedTime  string      `json:"created_time"`
    Progress     int         `json:"progress"`
    ErrorMessage *string     `json:"error_message"`
}

type MediaFile struct {
    FileURL  string `json:"file_url"`
    FileType string `json:"file_type"`
}

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    var taskData TaskData

    if err := json.NewDecoder(r.Body).Decode(&taskData); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    if taskData.Status == "finished" {
        // Task completed successfully
        fmt.Printf("Task %s completed\n", taskData.TaskID)
        for _, file := range taskData.Files {
            fmt.Printf("Generated file: %s\n", file.FileURL)
            // Download and process the file
        }
    } else if taskData.Status == "failed" {
        // Task failed
        fmt.Printf("Task %s failed: %s\n", taskData.TaskID, *taskData.ErrorMessage)
        // Handle the failure
    }

    // Return 200 to acknowledge receipt
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]bool{"received": true})
}

func main() {
    http.HandleFunc("/webhook/generation-complete", handleWebhook)

    // Use HTTPS
    err := http.ListenAndServeTLS(":443", "cert.pem", "key.pem", nil)
    if err != nil {
        panic(err)
    }
}

Security Best Practices

Verify requests: Validate X-Webhook-Timestamp and X-Webhook-Signature before processing callbacks.

Idempotency: Design your webhook handler to be idempotent in case of duplicate deliveries

Async processing: Process the callback asynchronously and return 200 quickly to avoid timeouts

Logging: Log all webhook requests for debugging and monitoring

Testing

Using ngrok for Local Testing

During development, you can use ngrok to expose your local server:

# Start your local webhook server on port 3000
node webhook-server.js

# In another terminal, start ngrok
ngrok http 3000

# Use the HTTPS URL provided by ngrok as your callback_url
# Example: https://abc123.ngrok.io/webhook/generation-complete

Webhook vs Polling

Method	Best For	Pros	Cons
Webhooks	Production systems	Real-time notifications, no polling overhead	Requires public endpoint, harder to debug
Polling	Development, simple integrations	Easy to implement, no server required	Higher latency, consumes more resources

For production systems handling high volumes, webhooks are recommended to reduce API calls and get instant notifications.

Next Steps

Task Status

Learn about polling task status

Image Generation

Generate images with GPT-4o

Video Generation

Create videos with Sora 2

Quick Start

Back to Quick Start guide

Overview

Image Model

Video Model

Music Model

Chat Model

3D Model

Task Management

Webhook Callbacks

Webhook Callbacks

How It Works

Callback Request

Request Headers

Request Body

Failed Task Callback

Signature Verification

Python Verification

Node.js Verification

Requirements

Retry Policy

Example Implementation

Python (Flask)

Node.js (Express)

Go

Security Best Practices

Testing

Using ngrok for Local Testing

Webhook vs Polling

Next Steps

Task Status

Image Generation

Video Generation

Quick Start

​Webhook Callbacks

​How It Works

​Callback Request

​Request Headers

​Request Body

​Failed Task Callback

​Signature Verification

​Python Verification

​Node.js Verification

​Requirements

​Retry Policy

​Example Implementation

​Python (Flask)

​Node.js (Express)

​Go

​Security Best Practices

​Testing

​Using ngrok for Local Testing

​Webhook vs Polling

​Next Steps

Task Status

Image Generation

Video Generation

Quick Start

Webhook Callbacks

How It Works

Callback Request

Request Headers

Request Body

Failed Task Callback

Signature Verification

Python Verification

Node.js Verification

Requirements

Retry Policy

Example Implementation

Python (Flask)

Node.js (Express)

Go

Security Best Practices

Testing

Using ngrok for Local Testing

Webhook vs Polling

Next Steps