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
- Read the raw body bytes before you parse them.
- Compute the HMAC-SHA256 of
timestamp + "." + raw body. - Compare it in constant time with
X-Sociaro-Signature; if that fails andX-Sociaro-Signature-Previousis present, compare with it. - Reject a timestamp more than 300 seconds from now.
- Store the verified event durably with the body's
job_idas a unique key, in one operation (for exampleINSERT ... ON CONFLICT (job_id) DO NOTHING): a conflict means you already have this event.Idempotency-Keyis not covered by the signature; it carries the same value asjob_id, and a mismatch means reject. - Then answer
2xxand process the event afterwards. A2xxnormally 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.