Webhooks

You add endpoints on the Webhooks page in this console. Owners and admins can add, edit, and delete them. Any member can view them. A new endpoint gets every event type, including ones we add later. Set an event filter if you only want some of them.

• Use HTTPS on port 443. The URL has to be reachable from the public internet.
• pika.art hosts aren’t accepted.
• Answer 2xx right away. Do the slow work after you’ve replied.
• We don’t follow redirects, so register the final URL.

Send test on an endpoint’s page posts a signed webhook.test event, so you can check the URL, the signature, and your handler without running a job. Every endpoint receives it, whatever its event filter says, and it makes a single attempt with no retries.

Any media submit takes an optional webhook_url. Pika posts that one job’s terminal event there, so a script can get a callback without registering anything first.

POST https://api.dev.pika.art/v1/media/pika/pika-2.5/text-to-video
authorization: Bearer $PIKA_API_KEY
content-type: application/json

{
  "prompt": "a paper boat crossing a puddle",
  "webhook_url": "https://example.com/pika/webhooks"
}

These deliveries are signed with your organization’s per-request secret rather than an endpoint’s. Reveal it on the Webhooks page in this console, or read it from GET /v1/webhooks/secret. Everything else is the same: the envelope, the webhook-* headers, the Standard Webhooks verification, and the retry schedule.

• The URL has to pass the same checks as a registered one: HTTPS on port 443, reachable from the public internet, not a pika.art host, no credentials.
• A delivery can reach you before the submit response does. Match it to the job with data.id and dedupe on webhook-id.
• Reusing an idempotency key with a different webhook_url is a 409.
• A job that fails sends media.job.failed to the same URL, so you don’t have to poll for the failure.

POST https://example.com/pika/webhooks
content-type: application/json
user-agent: pika-webhooks/1.0
webhook-id: msg_0f1e4b7a-9c33-4d81-b0a2-6e5d8c7f41ab
webhook-timestamp: 1786650067
webhook-signature: v1,LWSb0oRhsMhAaMLpQGXjNL0aOEmMPuTv0AUKZBFPEUE=

{
  "type": "media.job.completed",
  "timestamp": "2026-08-14T09:41:07.482913+00:00",
  "data": {
    "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
    "status": "completed",
    "model_id": "pika/pika-2.5/text-to-video",
    "runtime_s": 42.7,
    "output": {
      "media_type": "video",
      "video": {
        "url": "https://api.dev.pika.art/v1/files/output.mp4",
        "content_type": "video/mp4"
      }
    },
    "error": null
  }
}

• webhook-id identifies the event. Retries and replays reuse it, so if you’ve seen an id before, you already have the event.
• webhook-timestamp is the unix time of this attempt, not of the event.
• data is the same job object that GET /v1/media/jobs/{request_id} returns once the job is done.
• runtime_s is best effort. It can be null.

Give your Standard Webhooks library the raw request bytes and the three webhook-* headers. Use the raw bytes, not a re-serialized copy of the JSON, or the signature won’t match.

from fastapi import FastAPI, HTTPException, Request
from standardwebhooks import Webhook, WebhookVerificationError

app = FastAPI()
webhook = Webhook(PIKA_WEBHOOK_SECRET)


@app.post("/pika/webhooks")
async def receive(request: Request) -> dict:
    try:
        event = webhook.verify(await request.body(), dict(request.headers))
    except WebhookVerificationError:
        raise HTTPException(status_code=400, detail="invalid signature")

    handle(event["type"], event["data"])
    return {"ok": True}

• Libraries reject a timestamp more than five minutes off. That stops someone from replaying a delivery they captured earlier.
• While a secret is rotating, the header holds more than one signature. Matching any of them is valid, and libraries already handle that.
• If verification fails, answer 4xx and stop. Don’t read the body.

import base64
import hashlib
import hmac
import time


def verify(secret, body, msg_id, timestamp, signature_header):
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("timestamp outside tolerance")

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()
    ).decode()

    for part in signature_header.split(" "):
        version, _, signature = part.partition(",")
        if version == "v1" and hmac.compare_digest(expected, signature):
            return
    raise ValueError("no matching signature")

A delivery succeeds when your endpoint answers with any 2xx within 20 seconds. Anything else is a failed attempt, and we try again.

• Attempts are spaced roughly 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 14 hours, and 24 hours apart, with jitter.
• A Retry-After header in seconds pushes the next attempt back, up to 1 hour. It can’t make us retry sooner.
• If you answer 410 Gone, we disable the endpoint. It shows as Disabled (gone), and you can turn it back on from its page.
• After the last attempt, the delivery is marked failed. You can replay it from the endpoint’s page.
• Every attempt reuses the same webhook-id, so dedupe on it.
• A webhook.test event is the exception: it makes one attempt and never retries.

When an attempt fails, we record why. You can see recent deliveries and every attempt on the endpoint’s page in this console.

Each endpoint has its own signing secret, and per-request deliveries share one organization-wide secret. Both are base64 with a whsec_ prefix. Reveal an endpoint’s from its page and the organization’s from the Webhooks page, and rotate either the same way: you pick how long the old secret stays valid, immediately, one hour, or one day.

During that overlap, both secrets sign every delivery, so webhook-signature holds two values separated by a space. Either signature is valid, so you can switch over without dropping an event.

webhook-signature: v1,LWSb0oRhsMhAaMLpQGXjNL0aOEmMPuTv0AUKZBFPEUE= v1,tQ9nS2pKcW4Hs1dRz7yVbXm0gJ3FfN8uLoEiA6TrCxU=