Delivery

Webhooks

Skip polling entirely. Pass a callbackUrl on any create or post-process job and PicoBerry POSTs a signed event to your server the moment the asset finishes.

Enable it on a job

Add two optional fields to any generation request — from-text, from-image, images, remesh, texture, animate:

Parameter	Description
callbackUrlOPTIONAL string	Public `https://` URL to POST the finished asset to. Private / internal IPs are rejected. Max 2,048 chars.
webhookSecretOPTIONAL string	HMAC signing secret. When set, deliveries carry an `X-PB-Signature` header you can verify. Strongly recommended.

create with callback

curl -X POST https://api.picoberry.ai/v1/models/from-text \
  -H "Authorization: Bearer pb_live_xxx" -H "Content-Type: application/json" \
  -d '{"prompt":"a stylized treasure chest","engine":"tripo",
       "callbackUrl":"https://example.com/webhooks/picoberry",
       "webhookSecret":"whsec_your_secret"}'

requests.post(f"{BASE}/v1/models/from-text", headers=headers, json={
    "prompt": "a stylized treasure chest", "engine": "tripo",
    "callbackUrl": "https://example.com/webhooks/picoberry",
    "webhookSecret": "whsec_your_secret"})

await fetch(`${BASE}/v1/models/from-text`, { method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "a stylized treasure chest", engine: "tripo",
    callbackUrl: "https://example.com/webhooks/picoberry",
    webhookSecret: "whsec_your_secret" }) });

Events

PicoBerry delivers one event when the job reaches a terminal state:

asset.succeeded the asset finished — files are readyasset.failed the job failed — credits were refunded

Delivery

The request body's data is byte-for-byte the same object you'd get from GET /v1/assets/{id}.

POST <your callbackUrl>

X-PB-Event: asset.succeeded
X-PB-Delivery-Id: 7f3a1b2c-…         # idempotency key — dedupe on this
X-PB-Signature: t=1785920000,v1=<hex>   # present when webhookSecret was set
Content-Type: application/json

{
  "event": "asset.succeeded",
  "deliveryId": "7f3a1b2c-…",
  "createdAt": "2026-08-05T09:12:00.000Z",
  "data": { /* identical to GET /v1/assets/{id} — id, taskStatus, files, … */ }
}

Verify the signature

v1 is the HMAC-SHA256 of the string "<t>.<raw-request-body>", keyed with your webhookSecret. Recompute it over the raw body (before JSON parsing), compare in constant time, and reject stale timestamps (> 5 min) to stop replays. Dedupe on X-PB-Delivery-Id.

Node.js (express)

const crypto = require("crypto");

function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Python (flask)

import hmac, hashlib, time

def verify(header, raw_body, secret):
    parts = dict(p.split("=") for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.{raw_body}".encode(),
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts["v1"], expected)

Respond fast Return 2xx within a few seconds and do heavy work asynchronously. Non-2xx responses and timeouts are retried with exponential backoff, so make your handler idempotent using X-PB-Delivery-Id.