Sociaro

Webhooks — signed job notifications with retries

Instead of polling, give POST /v2/jobs a callback_url and we POST to it when the job reaches a terminal status. The envelope is on Jobs API.

What is sent

One event, job.finished, for all four terminal statuses: succeeded, failed, canceled and expired; status in the body says which.

POST /your/webhook HTTP/1.1
Content-Type: application/json
Idempotency-Key: job_5cc8778b79574aaa7ea8fc09caec23e5
X-Sociaro-Timestamp: 1763287331
X-Sociaro-Signature: <64 lowercase hex characters>
header what it is
Idempotency-Key The job id, the same as job_id in the body.
X-Sociaro-Timestamp Unix time in seconds, as a decimal string.
X-Sociaro-Signature Lowercase hex HMAC-SHA256 of timestamp + "." + raw body.
X-Sociaro-Signature-Previous Only during the 24 hours after you rotate the secret: the same message signed with the previous secret.

The body is the object GET /v2/jobs/{id} returns, plus event and job_id:

{"event": "job.finished",
 "job_id": "job_5cc8778b79574aaa7ea8fc09caec23e5",
 "id": "job_5cc8778b79574aaa7ea8fc09caec23e5",
 "status": "succeeded",
 "model": "alibaba/wan-2-7-image",
 "media": "image",
 "created_at": "2026-08-24T08:54:16.457268+00:00",
 "deadline_at": "2026-08-24T09:04:16.457268+00:00",
 "completed_at": "2026-08-24T08:55:28.624694+00:00",
 "retention_until": "2026-09-23T08:54:16.457268+00:00",
 "cost_usd": 0.03,
 "outputs": [{"url": "https://cdn.sociaro.com/v2/job_5cc8778b79574aaa7ea8fc09caec23e5/0-3f21c8ead6af7a981b5bf99fd705a745.png",
              "type": "image",
              "content_type": "image/png",
              "expires_at": "2036-08-24T08:55:28.608057+00:00"}]}

The example is formatted for reading; the body you receive is compact JSON, so verify the raw bytes exactly as received.

outputs is present only when status is succeeded; error only when the job has one (failed, expired, canceled). cost_usd is final when the event is sent. Ignore keys you do not know.

The signing secret

There is one secret per organisation, shared by all its API keys. Find it in the customer console: Keys tab, Webhook signing secret, with the buttons Show secret and Rotate.

The HMAC key is the whole secret string as shown, whsec_ prefix included, as UTF-8 bytes.

After a rotation the previous secret keeps working for 24 hours, through X-Sociaro-Signature-Previous, so you can switch your receiver without losing events. A second rotation within those 24 hours is refused until the window ends.

Verify a delivery

  1. Read the raw body bytes before you parse them.
  2. Compute the HMAC-SHA256 of timestamp + "." + raw body.
  3. Compare it in constant time with X-Sociaro-Signature; if that fails and X-Sociaro-Signature-Previous is present, compare with it.
  4. Reject a timestamp more than 300 seconds from now.
  5. Store the verified event durably with the body's job_id as a unique key, in one operation (for example INSERT ... ON CONFLICT (job_id) DO NOTHING): a conflict means you already have this event. Idempotency-Key is not covered by the signature; it carries the same value as job_id, and a mismatch means reject.
  6. Then answer 2xx and process the event afterwards. A 2xx normally ends the retries, but the same event can still arrive again, which is why step 5 deduplicates every delivery.
import hashlib, hmac, time

def verify(secret, headers, raw, now=None):
    ts = headers.get("X-Sociaro-Timestamp")
    if not ts or not (ts.isascii() and ts.isdigit() and len(ts) <= 12) or abs((now or time.time()) - int(ts)) > 300:
        return False
    for h in ("X-Sociaro-Signature", "X-Sociaro-Signature-Previous"):
        if headers.get(h):
            want = hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
            if hmac.compare_digest(want.encode(), headers[h].encode()):
                return True
    return False

Delivery and retries

A delivery succeeded when your URL answers any 2xx within 15 seconds. Redirects are not followed, and the URL must be a public https address.

We make up to 10 attempts per job, each with a fresh timestamp and signature, not earlier than:

attempt not earlier than, after the job finishes
1 at once
2 1 min
3 6 min
4 21 min
5 1 h 21 min
6 3 h 21 min
7 7 h 21 min
8 13 h 21 min
9 19 h 21 min
10 25 h 21 min

After the tenth attempt the event is dropped. GET /v2/jobs/{id} and the lookup by key always work, so keep polling as the fallback for anything you must not miss.