Percify API webhooks: payloads and signature headers

Pass a webhook URL when you start a Percify API job and Percify POSTs the result when it ends, with X-Percify-Timestamp and X-Percify-Signature headers.

A Percify webhook is a single HTTPS POST that Percify sends to your server when an API job succeeds or fails. You turn it on per job by passing a webhook URL when you start it; there is no account-wide webhook setting. Each POST carries the job’s result as JSON plus X-Percify-Timestamp and X-Percify-Signature headers.

Which calls accept a webhook?

Start call	Field	Sent when
POST /v3/playground/v1/run	webhook in the body	The generation succeeds or fails
POST /v3/replicate/v1/analyses/{id}/replicate	webhook in the body	The replication run is done or failed
POST /v3/mascot/api	webhook in the body	The short video is done or failed

The MCP tools generate, replicate_video and make_video take the same webhook argument.

URL requirements

• It must be a valid URL that starts with https://.
• The host must resolve to a public IP address. localhost, .local and .internal hosts and private network addresses are refused.
• Percify checks the URL when you start the job, so a bad URL fails the start call with a 400 such as webhook must use https.

To test locally, expose your server through a public HTTPS tunnel.

What Percify sends

Every webhook is a POST with these headers:

Header	Value
Content-Type	application/json
User-Agent	Percify-Webhook/1
X-Percify-Timestamp	Unix time in seconds when the POST was signed
X-Percify-Signature	sha256= followed by a hex HMAC-SHA256 of {timestamp}.{raw body}

Generation payload

{
  "id": "3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83",
  "modelId": "infinitetalk-fast",
  "status": "succeeded",
  "output": {
    "type": "video",
    "urls": ["https://cdn.percify.io/media-assets/playground/3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83-0"]
  },
  "error": null
}

A failed generation has "status": "failed", "output": null and the reason in error. Its credits were already refunded.

Replication payload

The same fields as GET /v3/replicate/v1/runs/{id}, plus "event": "replication.completed". Check status for done or failed.

Short video payload

{ "jobId": "7a1e4c2b-0d9f-4b8e-a3c5-5f2e9d1b6a70", "status": "done", "videoUrl": "https://cdn.percify.io/…", "creditsSpent": 68 }

A failed job sends { "jobId": "…", "status": "failed", "error": "…" }.

Delivery rules

• One attempt. Percify sends each webhook once and does not retry. If your server is down, recover with the polling endpoint.
• Your response is not read. Return 200 quickly and do slow work afterwards.
• No polling needed. Percify checks running jobs in the background, so the webhook is sent even if you never poll.

Verify a webhook

The signature is an HMAC-SHA256 of the timestamp, a dot and the exact raw request body, keyed with a signing secret for your account. The developer console does not show that secret, so you cannot check X-Percify-Signature yourself today.

Treat the webhook as a notification and confirm it with your API key instead: take the id from the body and read the job from Percify. Anyone can POST to your URL, but only Percify can answer GET /v1/generations/{id} for your key.

Node.js (Express)

import express from "express";

const app = express();
app.use(express.json());

app.post("/percify/webhook", async (req, res) => {
  res.sendStatus(200); // answer fast; Percify does not retry

  const { id } = req.body ?? {};
  if (typeof id !== "string") return;

  const r = await fetch(`https://api.percify.io/v3/playground/v1/generations/${id}`, {
    headers: { Authorization: `Bearer ${process.env.PERCIFY_API_TOKEN}` },
  });
  if (!r.ok) return; // not a generation from your account

  const { data } = await r.json();
  if (data.status === "succeeded") {
    // save data.output.urls
  }
});

app.listen(3000);

For replication runs, confirm with GET /v3/replicate/v1/runs/{id}. For short videos, use GET /v3/mascot/api/{jobId}.

Tips

• Store the job id when you start it, and ignore webhooks for ids you do not know.
• Make your handler safe to run twice for the same id.
• Keep a slow fallback poll for jobs that never reported back, for example if your server was down when the POST arrived.

Related

Async jobs and polling

Statuses, timeouts and refunds.

Start a generation

Where the webhook field goes.

Get a generation

Confirm a webhook with your key.

Code examples

Node.js, Python and cURL end to end.