Webhook Callbacks

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

How It Works

Submit with callback URL: Include a callback_url in your 3D 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 model 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 3D 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": "9OTM0HH9LBS63LF0",
  "status": "finished",
  "files": [
    {
      "file_url": "https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_1.glb",
      "file_type": "3d"
    },
    {
      "file_url": "https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_2.png",
      "file_type": "image"
    },
    {
      "file_url": "https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_3.glb",
      "file_type": "3d"
    }
  ],
  "created_time": "2026-05-12T02:36:12",
  "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 3D 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

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 3D status endpoint.

Important Notes

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.

Next Steps

Task Status

Learn about polling 3D task status

Meshy 6 3D

Generate 3D models with Meshy 6

Tripo3D H3.1

Generate 3D models with Tripo3D H3.1

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

Requirements

Retry Policy

Important Notes

Next Steps

Task Status

Meshy 6 3D

Tripo3D H3.1

​Webhook Callbacks

​How It Works

​Callback Request

​Request Headers

​Request Body

​Failed Task Callback

​Signature Verification

​Requirements

​Retry Policy

​Important Notes

​Next Steps

Task Status

Meshy 6 3D

Tripo3D H3.1

Webhook Callbacks

How It Works

Callback Request

Request Headers

Request Body

Failed Task Callback

Signature Verification

Requirements

Retry Policy

Important Notes

Next Steps