PiAPI
HomeWorkspace
HomeWorkspace
Join Discord
  1. Resources
  • Get Started
    • Overview
    • Quickstart
    • Make Instruction: How to Use PiAPI to Build a Workflow on Make?
  • Endpoints
    • Song(Udio)
      • Song API Task Creation Examples
      • [Udio] Song Extend
      • Get Task
      • Create Task
      • [Udio] Generate Lyrics
    • Kling
      • Lipsync With PiAPI Kling API Examples
      • Motion Brush With PiAPI Kling API Example
      • Kling Elements Video Generation API
      • Kling Effects Video Generation
      • Cancel Task
        • Cancel Tasks
        • Cancel Task
      • Get Task
      • Create Task
      • Kling Virtual Try-On
      • Kling Effects
    • Hailuo
      • Hailuo Director Mode Example
      • Generate Video
      • Get Task
    • Flux
      • Flux with LoRA and Controlnet
      • Available LoRA and Controlnet
      • Flux API with Redux Variation, Fill, Inpaint and Outpaint
      • Create Task
        • Text to Image
        • Image to Image
      • Get task
    • AI Hug
      • Get Task
      • Create Task
    • LLM
      • Use Cases for GPT-4o Image API
      • How To Avoid Timeouts in Completion API
      • GPT-4o Image Generation API
      • LLM API | Basic Completions
      • Get Task
    • Midjourney
      • PiAPI Penalties on Midjourney Usage
      • Detailed Explaination on Midjourney Task Result
      • Midjourney V7 API Instructions
      • Create Task
        • Imagine
        • Upscale
        • Variation
        • Reroll
        • Describe
        • Seed
        • Blend
        • Inpaint
        • Outpaint
        • Pan
      • Cancel Task
        • Cancel Task
        • Cancel Tasks
      • Get Task
    • Faceswap
      • Multi Faceswap
      • Image Faceswap
      • Video Faceswap
      • Get Task
    • TTS
      • Zeroshot Text-to-Speech F5-TTS
      • Get Task
    • Trellis
      • Create Task
      • Get Task
    • Luma Dream Machine
      • Cancel Task
        • Cancel Tasks
        • Cancel Task
      • Create Task
      • Get Task
    • WanX
      • Generate WanX Task with LoRA Using PiAPI
      • Available LoRA Types for Wanx
      • Use Cases for Wanx LoRA
      • Use Cases for Wanx Control Camera
      • Create Task
      • Get Task
    • Skyreels
      • Create Task
      • Get Task
    • Framepack
      • Create Task
      • Get Task
    • Hunyuan Video
      • How to Make a Hunyuan API Call
      • Get Task
      • Generate Video
    • Mmaudio
      • Get Task
      • Generate Audio
    • DiffRhythm
      • Generate Audio
      • Get Task
    • Tools
      • File Upload API
      • Video Upscale
      • Video Upscale-Get Task
      • Remove Background API
      • Remove Background-Get Task
      • Segment With Prompt API
      • Segment With Prompt API-Get Task
      • Image Upscale(Super Resolution) API
      • Image Upscale-Get Task
    • PiAPI Account Management
      • PiAPI Account Info
      • Task List Info
      • User Task History
  • Resources
    • Change Log
    • Output Storage
    • Unified API Schema
    • Webhook
    • Bulk Generation Service
    • Billings
    • PiAPI MCP Server
    • Workspace Manual
      • Host-your-account (HYA) | Back-up Account
      • Host-your-account (HYA) | Debug Checklist
      • Host-your-account (HYA) | Connected Account Status
    • Announcements
      • PiAPI 2025 January 1st Pricing Update
  • Legacy Documentation
    • Midjourney
      • Midjourney Webhook
      • Imagine
      • Reroll
      • Upscale
      • Variation
      • Inpaint
      • Outpaint
      • Pan
      • Describe
      • Blend
      • Seed
      • Fetch
      • Multi Fetch
      • Cancel
    • Face Swap
      • Video Faceswap
      • Multi-face-swap
      • Fetch
    • Dream Machine
      • Video Generation
      • Video Extend
      • Get Video Generation
    • Kling
      • Video Generation
      • Video Extend
      • Get Video Generation
  1. Resources

Webhook

Introduction#

To ensure timely updates and notifications, PiAPI offer webhook services integrated with our Unified API Schema.
When you create a task, you can specify a webhook endpoint. Our API service will then send an HTTP POST request to this URL whenever a task succeeds or fails.
Webhooks: Use Cases
1
Persisting Result Data and Files
Since input and output data (including any files) are automatically deleted after a set period, webhooks allow you to capture all metadata for completed tasks. This enables you to store the data in a database or save the output files to persistent storage before they are deleted.
2
Notification for Long-Running Tasks
Some tasks may take several minutes to complete. By using a webhook handler, you can send notifications—such as an email or a Slack message—when a task is completed.
3
Building Model Pipelines
Webhooks can capture the output of one long-running task and feed it into another model as input, enabling seamless automation across models.
📌
Webhooks are only supported in the Unified API Schema. While the legacy version of the API remains fully functional, webhook capabilities are exclusive to the new unified API.

Setting Up Webhooks#

To use webhooks, include the webhook_config field in the request body when creating a task. Specify the endpoint and secret.
//POST https://api.piapi.ai/api/v1/task 
{
    "model": "suno/v3-chorip",
    "task_type": "lyrics",
    "input": {},
    "config": {
        "webhook_config": {
            "endpoint": "",
            "secret": ""
        }
    }
}
FieldDescriptionDetails
endpointThe URL where the webhook will be sentEnsure that the receiving server is accessible by Cloudflare workers.
secretUsed to verify the request sourceIf a secret is provided, it will be included in the x-webhook-secret header.

Receiving Webhooks#

When will PiAPI send webhook notification#

When a task is created or completed (i.e., when a task enters the completed or failed status), PiAPI sends an HTTP POST request to the specified URL.
Additionally, webhook notifications are also sent for certain tasks whenever there is a status update in the processing mode. These tasks include:
1.
Music Generation tasks processed by Suno.
2.
Tasks processed by Midjourney, created by users with the Creator Plan or higher.

Request body#

The request body is in JSON format and includes two key fields: timestamp and data.
The timestamp helps in identifying duplicate notifications (such as in cases of retry), while the data field mirrors the response from the unified fetch API.
{
    "timestamp": 1723018391,
    "data": {}
}
FieldDescriptionDetails
timestampUnix timestampUseful for detecting duplicate notifications.
dataTask dataMatches the structure from the unified fetch API.
The output field is critical in webhook notifications as it reflects the current result or progress of the task, with content varying depending on the model and task type.
🚀
Here is an example of a webhook request for a Luma video generation task:
{
  "timestamp": 1724511853,
  "data": {
    "task_id": "58cb41b7-556d-46c0-b82e-1e116aa1a31a",
    "model": "luma",
    "task_type": "video_generation",
    "status": "completed",
    "config": {
      "webhook_config": {
        "endpoint": "https://webhook.site/xxxxx",
        "secret": "123456"
      }
    },
    "input": {
      "aspect_ratio": "16:9",
      "expand_prompt": true,
      "image_end_url": "https://i.imgur.com/CSmEZud.png",
      "image_url": "https://i.imgur.com/eJkSUnA.png",
      "loop": false,
      "user_prompt": ""
    },
    "output": {
      "generation": {
        "id": "ab9124ef-49d4-4da7-bf12-0c3891a3cca8",
        "prompt": "",
        "state": "completed",
        "created_at": "2024-08-24T15:01:52.727Z",
        "video": {
          "url": "https://storage.cdn-luma.com/dream_machine/49995d70-d0f3-4b0d-afb0-ec034107e4e2/watermarked_video08fe0802a4e104f1a80fb6c6c658710ee.mp4",
          "url_no_watermark": "https://img.midjourneyapi.xyz/ephemeral/db7420f9-8a24-48fd-ade5-ede803e835db.mp4",
          "width": 1168,
          "height": 864,
          "thumbnail": ""
        },
        "like": null,
        "estimate_wait_seconds": null
      }
    },
    "meta": {
      "created_at": "2024-08-24T23:01:12.3556324+08:00",
      "started_at": "2024-08-24T23:01:36.7432691+08:00",
      "ended_at": "2024-08-24T23:04:13.5301322+08:00",
      "usage": {
        "type": "luma_quota",
        "frozen": 30,
        "consume": 30
      }
    },
    "detail": {
      "account_id": 1,
      "is_using_private_pool": false
    },
    "logs": [],
    "error": {
      "code": 0,
      "message": ""
    }
  }
}
In webhook notifications, the output field within the data structure is particularly important as it represents the result (or latest progress) of the task. The content of the output field mirrors that of the output field in the response from the get task endpoint.

Handling Webhook Deliveries#

Your endpoint must return a successful status code (2xx) quickly to avoid timeouts before performing any complex logic.
To handle webhook requests, create an HTTP or HTTPS endpoint that accepts POST requests with a JSON payload. For local development, you can use HTTP, but once publicly accessible, the endpoint must support HTTPS.
The endpoint should handle POST requests with the event object in JSON format.
Always respond with a 2xx status code before performing any extended logic.
Here's an example of a Next.js webhook handler:

Webhook Retries#

If PiAPI does not receive a successful response (status 2xx), or if it encounters a 4xx or 5xx error, it will retry the webhook after 5 seconds. Up to 3 attempts will be made for each notification.

Best Practices for Using Webhooks#

1.
Use HTTPS for Security: Ensure your server uses HTTPS to protect data in transit, preventing unauthorized access.
2.
Timestamp Verification: The timestamp in webhook requests is crucial for:
Preventing Replay Attacks: Compare the request’s timestamp with the current system time. If the difference is too large, reject the request.
Deduplication: Use the timestamp to avoid processing the same event multiple times.
3.
Testing Webhooks: We recommend services like webhook.site to test and debug webhook requests before moving to production.
Previous
Unified API Schema
Next
Bulk Generation Service