OpenRouter video callback default vs Sume per-request webhooks

OpenRouter's video guide says you can configure a callback_url on each request or set a workspace default, and that it POSTs when a job reaches a terminal state, with optional HMAC-SHA256 signing. Sume accepts callback_url on POST /v1/videos too, but the docs describe it per request only; there is no workspace-wide default callback in the docs.

If you rely on a default to catch every job, you need to add the URL in your own submit code when you move to Sume.

What does OpenRouter document?

On the video generation page, the workflow is: POST /api/v1/videos, get a job id and polling URL, poll GET /api/v1/videos/{jobId} until completed, then download from the content URL with your API key in the Authorization header. Statuses run pending, in_progress, completed or failed. Instead of polling you set a callback_url per request or a workspace default; OpenRouter then sends a POST when jobs reach terminal states, with optional HMAC-SHA256 signature verification.

The page also notes video generation is ineligible for Zero Data Retention, because providers briefly retain outputs for async retrieval.

What does Sume document?

Sume's /v1/videos docs follow the OpenRouter field names, so callback_url is a request parameter that must be HTTPS. Sume POSTs once the job reaches a terminal state, signing the raw JSON body and sending x-sume-webhook-timestamp and x-sume-webhook-signature. The envelope is Sume's standard job webhook, not OpenRouter's video.generation.* events: the docs list job.completed, job.failed and job.canceled, and no progress events.

On the generic job endpoints, webhook_url and callback_url are aliases, and sending either without a mode selects webhook mode. The signing secret is derived per workspace: read it on the Webhooks tab of the dashboard or from GET /v1/webhooks/signing-secret with a key that has account:read.

How do I replace a workspace default?

Put the URL in one place in your code, a wrapper around the submit call, so every job carries it. Keep a polling fallback for jobs where delivery fails: Sume's webhook delivery statuses are pending, delivering, delivered, retrying, failed and exhausted, and the job record shows the delivery state.

Because the URL is per request, you can also route different jobs to different endpoints, which a single default cannot do.

import os, httpx

def submit(model: str, prompt: str, key: str) -> dict:
    callback = os.environ.get("SUME_CALLBACK_URL", "")
    if not callback.startswith("https://"):
        raise SystemExit("SUME_CALLBACK_URL must be https")
    r = httpx.post("https://api.sume.com/v1/videos",
        headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
                 "Idempotency-Key": key},
        json={"model": model, "prompt": prompt, "callback_url": callback})
    return r.json()

print(submit("sume/auto", "A product clip on a desk", "demo-0001"))

What about the download step?

OpenRouter's page says to download from the content URL with your API key in the Authorization header. Sume's /v1/videos docs show the same call, GET /v1/videos/{jobId}/content?index=0 with a bearer header, and the job result also carries Sume-owned artifact URLs under media.sume.com. Which one to use in a webhook handler: the job result, so you do not need the key at the download step.

Which should you use?

If you want a single workspace-level callback for every job from many services, OpenRouter's default is convenient. If you want explicit per-job routing and a signed envelope with a documented verification recipe, Sume's design is fine, at the cost of one more line in your submit code. Read the deltas in OpenRouter video webhook events vs Sume job events and the full Sume webhook docs.