PicX Studio

Webhooks

Receive signed notifications when asynchronous generations complete or fail.

View as Markdown

Webhooks notify your server when a generation finishes, so you do not have to poll. They apply to every asynchronous generation — video, and (since API version 2026-08-01) images submitted with a delivery target.

There are two ways to name a target, and which you can use depends on how you authenticate:

How you set itAuth to set upSigned with
Per-request URLcallback_url or webhook: {url} in the generation bodyAPI keya secret derived from your API key
Registered webhookcreate in the console, then webhook: {id}signed-in sessionits own whsec_…

Webhook registration (create, list, test, delete) lives on the console's session-authenticated API under /api/webhooks, not on the public /v1 surface. An API key alone cannot register a webhook. If you provision programmatically, use callback_url or webhook: {url} on the generation request — it needs no setup and is signed and logged the same way.

Delivery inspection is different: GET /v1/generations/{id}/deliveries, GET /v1/webhooks/{id}/deliveries and POST /v1/webhooks/deliveries/{id}/redeliver are published under /v1 and work with an API key. In the SDKs that is generations.deliveries(), webhooks.deliveries() and webhooks.redeliver(), available from picx-ai 0.3.1.

For images specifically, Async Image Generation covers the whole flow end to end.

The simplest path: a per-request URL

No registration, no console — works with an API key alone:

import { PicX } from "picx-ai";

const picx = new PicX(process.env.PICX_API_KEY);

const job = await picx.images.generate({
  prompt: "a cat on a windowsill",
  callback_url: "https://your-server.com/hooks/picx",
});

console.log(job.id); // persist this to correlate the delivery
import os
from picx import PicX

picx = PicX(os.environ["PICX_API_KEY"])

job = picx.images.generate(
    "a cat on a windowsill",
    callback_url="https://your-server.com/hooks/picx",
)
curl -X POST https://api.picxstudio.com/v1/images/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a cat on a windowsill","callback_url":"https://your-server.com/hooks/picx"}'

The same field works on POST /v1/images/edit and POST /v1/videos/generate.

The secret for this mode is derived from the API key that made the request — stable, distinct per key, and readable from the key's detail view in the developer console. It is not returned by any /v1 endpoint.

Bind inline through the webhook field

Equivalent to callback_url, but recorded against the generation as an explicit binding (mode: "inline") and delivered with the strict envelope rather than the legacy flat body:

const job = await picx.video.create({
  prompt: "a cat jumping off a table",
  duration: 5,
  resolution: "480p",
  webhook: { url: "https://your-server.com/webhook" },
});
job = picx.video.create(
    prompt="a cat jumping off a table",
    duration=5,
    resolution="480p",
    webhook_url="https://your-server.com/webhook",
)

Resolution order is first match wins: webhook.id, then webhook.url, then callback_url.

Managing registered webhooks

Registration requires a signed-in console session. Paths are under /api, not /v1.

ActionPathAPI key?
CreatePOST /api/webhooksno — console only
ListGET /api/webhooksno — console only
Test deliveryPOST /api/webhooks/{id}/testno — console only
DeleteDELETE /api/webhooks/{id}no — console only

Delivery inspection is available to API keys, under /v1:

ActionPathAPI key?
Deliveries for one generationGET /v1/generations/{id}/deliveriesyes
Deliveries for one webhookGET /v1/webhooks/{id}/deliveriesyes
RedeliverPOST /v1/webhooks/deliveries/{id}/redeliveryes

The signing secret (whsec_…) is returned only once, when you create the webhook. Store it immediately.

Inspecting deliveries

When a result never turns up, this is the call that tells you why — it shows every event fired for a generation and every attempt made, including inline and legacy callback_url deliveries that have no registered webhook row.

const { deliveries, total } = await picx.generations.deliveries(job.id);
for (const d of deliveries) {
  console.log(d.event_type, d.outcome, d.status_code, d.target_url);
  console.log(d.attempts); // [{ n: 1, at: ..., status: 503, ms: 812, error: null }]
}
log = picx.generations.deliveries(job.id)
for d in log.deliveries:
    print(d.event_type, d.outcome, d.status_code, d.target_url)
curl https://api.picxstudio.com/v1/generations/GENERATION_ID/deliveries \
  -H "Authorization: Bearer pxsk_your_key"

For a registered webhook, filter to just the problems:

const { deliveries } = await picx.webhooks.deliveries(webhookId, {
  outcome: "exhausted",
  limit: 50,
});

outcome accepts delivered, failed, pending_retry or exhausted; anything else is rejected with a 400 rather than quietly matching nothing. limit caps at 100.

Once you have fixed your endpoint, replay a delivery:

const result = await picx.webhooks.redeliver(deliveryId);
console.log(result.outcome, result.status_code);
result = picx.webhooks.redeliver(delivery_id)

The replay reuses the original payload and event_id, so a consumer that dedupes on X-PicX-Delivery can safely ignore one it already handled. The recorded target URL is re-validated first — a delivery whose hostname now resolves to a private address is refused with a 400 rather than fetched.

Once registered, binding a generation to a webhook by id needs only an API key:

const job = await picx.images.generate({
  prompt: "a cat",
  webhook: { id: "0b9c1e42-…", events: ["generation.completed"] },
});
job = picx.images.generate("a cat", webhook_id="0b9c1e42-…")

A bad or foreign webhook id fails the submit with 404, before credits are spent, rather than running a generation that delivers nowhere.

Delivery headers

POST /your/webhook HTTP/1.1
Content-Type: application/json
X-PicX-Event: generation.completed
X-PicX-Delivery: evt_e7e4a0602e364e26ba574c4d0ca03027
X-PicX-Attempt: 1
X-PicX-Generation: d3bfa107-6475-4f5b-ad32-c65c3e1b0377
X-PicX-Signature: t=1787654321,v1=6f1c2a9d8e...

Event payload

{
  "id": "evt_e7e4a0602e364e26ba574c4d0ca03027",
  "event": "generation.completed",
  "created_at": "2026-08-25T16:02:47.802789+00:00",
  "api_version": "2026-08-01",
  "webhook_id": null,
  "data": {
    "generation_id": "d3bfa107-6475-4f5b-ad32-c65c3e1b0377",
    "status": "completed",
    "type": "image",
    "model": "gemini-3.1-flash-image-preview",
    "output_url": "https://cdn.picxstudio.com/api/generated/image_6830d3ca.png",
    "error_message": null,
    "credits_used": 35
  }
}

The event name is in event, and the delivery id in id. data.type is image or video.

Two event types are sent by default — generation.completed and generation.failed — and generation.cancelled can be subscribed to explicitly. On a failure output_url is null, error_message is populated, and the credits are refunded.

api_version is bumped only on a breaking payload change, so you can pin against it.

A callback_url target receives a superset body for backwards compatibility: the envelope above plus the data fields flattened onto the top level (generation_id, status, output_url, …). Reading data.output_url works for every target type, so prefer it.

Delivery behaviour

PropertyValue
Attempts3
Backoff1s, then 2s
Per-attempt timeout10s
Redirectsnot followed
Successany 2xx

Reply 2xx promptly and move heavy work off the request — a timeout counts as a failed attempt, and after three the delivery is marked exhausted.

Deliveries are at-least-once. Dedupe on X-PicX-Delivery (or the body's id) and keep handlers idempotent.

Never treat the webhook as your only path to the result. If a delivery is missed the generation still succeeded — read it with GET /v1/generations/{id} using the id from the 202. Persist that id at submit time.

Callback URL requirements

Validated at submit time; a bad target fails with 400 before credits are spent.

  • Scheme http or https; use https in production
  • Hostname must resolve to a public address
  • Loopback, private ranges and link-local (including the cloud metadata address) are rejected
  • Maximum 2048 characters

The guard fails closed, so a hostname that does not resolve is rejected. For local development use a tunnel (cloudflared tunnel --url http://localhost:3000) rather than localhost.

Always verify the signature before trusting a delivery. The X-PicX-Signature header has the form t={timestamp},v1={signature}: compute HMAC-SHA256 over the exact string "{timestamp}." followed by the raw request body, using your webhook secret, then compare in constant time.

Verify the signature

Verify against the raw bytes, before any JSON parsing or re-serialisation — a framework that reformats the body will invalidate the digest.

python

import hmac, hashlib
from flask import Flask, request, abort, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret"

def verify_signature(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp, signature = parts["t"], parts["v1"]
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    header = request.headers.get("X-PicX-Signature", "")
    if not header or not verify_signature(WEBHOOK_SECRET, header, request.get_data()):
        abort(401)
    event = request.get_json()
    if event["event"] == "generation.completed":
        print("Ready:", event["data"]["output_url"])
    elif event["event"] == "generation.failed":
        print("Failed:", event["data"]["error_message"])
    return jsonify(ok=True)

javascript

import express from "express";
import crypto from "crypto";

const app = express();
const WEBHOOK_SECRET = "whsec_your_secret";

function verifySignature(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const signed = `${parts.t}.` + rawBody.toString();
  const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex");
  const a = Buffer.from(parts.v1 || "", "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.headers["x-picx-signature"] || "";
  if (!verifySignature(WEBHOOK_SECRET, header, req.body)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  const event = JSON.parse(req.body.toString());
  if (event.event === "generation.completed") {
    console.log("Ready:", event.data.output_url);
  }
  res.json({ ok: true });
});

Deliveries are retried up to 3 times with backoff on non-2xx responses. Respond quickly with a 2xx once you have accepted the event, then do heavy work asynchronously.

Build with PicX

One API key and one credit balance across the REST API, MCP server, CLI and SDKs.