Webhooks

Add callback_url to an image or video generation request to receive a POST request when the task reaches completed or failed.

{
  "model": "gpt-image-2",
  "prompt": "A technical cutaway illustration of a compact camera",
  "callback_url": "https://api.example.com/webhooks/apipod/opaque-route-token"
}

Callback request

APIPod sends Content-Type: application/json and User-Agent: APIPod-Callback/1.0.

{
  "task_id": "img_example_task_id",
  "request_id": "req_example_request_id",
  "status": "completed",
  "result": [
    "https://example.com/generated-image.png"
  ],
  "created_at": "2026-08-10T09:00:00Z",
  "completed_at": "2026-08-10T09:01:30Z"
}

A failed task uses the same envelope:

{
  "task_id": "img_example_task_id",
  "request_id": "req_example_request_id",
  "status": "failed",
  "error": "Upstream request failed. Please retry later.",
  "error_code": "UPSTREAM_CAPACITY_EXHAUSTED",
  "created_at": "2026-08-10T09:00:00Z",
  "completed_at": "2026-08-10T09:01:30Z"
}

error_code is optional. Do not infer success from its absence; use status.

Delivery behavior

Any HTTP status from 200 through 299 acknowledges the callback.
Non-2xx responses and network errors are retried.
APIPod currently makes up to five delivery attempts with exponential backoff.
Duplicate delivery is possible, so receivers must be idempotent.
Callback delivery is asynchronous and does not change the task’s terminal state.

Secure the receiver

The current public callback contract does not include a signature header. Do not claim that a callback is authenticated solely because its JSON shape looks correct.

Use HTTPS and a high-entropy, unguessable token in the callback path.
Keep the callback URL server-side; do not expose it in client applications.
Match task_id and request_id against tasks your system created.
Store a processed-event key and make duplicate callbacks return the same successful outcome.
Validate field types and reject unexpectedly large bodies.
Return 2xx only after the callback has been durably accepted; process slow work asynchronously.
If authenticity is critical, query the authenticated status endpoint before applying irreversible business actions.

Minimal receiver

import express from "express";

const app = express();
app.use(express.json({ limit: "64kb" }));

app.post("/webhooks/apipod/:token", async (req, res) => {
  if (req.params.token !== process.env.APIPOD_WEBHOOK_TOKEN) {
    return res.sendStatus(404);
  }

  const { task_id, request_id, status } = req.body;
  if (!task_id || !request_id || !["completed", "failed"].includes(status)) {
    return res.sendStatus(400);
  }

  await persistIdempotently({ task_id, request_id, payload: req.body });
  return res.sendStatus(204);
});

Overview

Core concepts

Callback request

Delivery behavior

Secure the receiver

Minimal receiver

​Callback request

​Delivery behavior

​Secure the receiver

​Minimal receiver

Callback request

Delivery behavior

Secure the receiver

Minimal receiver