Appearance
Webhooks
Subscribe to a publication’s progress instead of polling. Webhook endpoints belong to your team, like API keys: each one receives the events of all brands (including brands added later) or of the brands you pick, and every event names its brand.
Register an endpoint
Register a URL, pick its brands and the events you care about:
curl: register an endpoint
curl -s -X POST "$API/webhooks" \
-H "Authorization: Bearer $SK" -H "Content-Type: application/json" \
-d '{
"url": "https://your-app.example/hooks/socialized",
"reach": "team",
"events": ["publication.completed", "publication.target.failed"]
}' | jqreach is "team" for every brand, or { "brandIds": ["brand_…"] } for the brands listed (GET /brands lists their IDs). The response includes a signing secret (whsec_…) returned once, like an API key. Store it; you’ll need it to verify deliveries. List your endpoints with GET /webhooks (without secrets) and remove one with DELETE /webhooks/{id}. The url must be https.
Who can manage endpoints
Anyone in the team can, from the dashboard. An API key needs the webhooks grant (Write or Admin to add and remove, Read to list) on every brand an endpoint covers: a key for some brands lists and removes only the endpoints for brands it reaches, and gets 403 BrandOutOfScopeError adding one beyond them; an endpoint for all brands takes a key for all brands.
Events
Every delivery’s body is the event, the brand it’s for, and its data:
A delivery’s body
{
"event": "publication.completed",
"brandId": "brand_…",
"data": { "publicationId": "pub_…", "status": "done" }
}| Event | Fires when |
|---|---|
publication.target.published | a single target goes live (its warnings list the steps that didn’t go through, each a { step, detail }: the lifecycle) |
publication.target.failed | a single target fails (its failure says why, as a target’s does: the lifecycle) |
publication.target.removed_remotely | a live post is observed to have been deleted manually on the platform |
publication.completed | a publication reaches a terminal state (done / partial / failed) |
connection.reauth_required | a platform needs a connection reconnected (reconnect to keep publishing) |
Verifying a delivery
Every delivery carries two headers:
X-Socialized-Signature:sha256=<hex>, an HMAC-SHA256 of the raw request body, keyed by your endpoint secret.X-Socialized-Event: the event’s ID (evt_…), the same across retries.
Recompute the signature over the bytes you received and compare. Reject anything that doesn’t match, so a forged request can’t be mistaken for ours.
Node.js: verify a delivery
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody: the request body exactly as received, before any JSON parsing.
// secret: the endpoint's signing secret (whsec_…), shown once when you created it.
// headers: the request's headers, names in lower case (as Node.js gives them).
const digest = createHmac('sha256', secret).update(rawBody).digest('hex');
const expected = Buffer.from(`sha256=${digest}`);
const received = Buffer.from(headers['x-socialized-signature'] ?? '');
const isValid =
received.length === expected.length && timingSafeEqual(received, expected);
// A retry resends the same event: skip an ID you have already handled.
const eventId = headers['x-socialized-event'];Compute the HMAC over the exact bytes of the body, before any JSON parsing: re-serializing changes the bytes and breaks the signature. Compare in constant time.
Delivery
Deliveries are retried with backoff until they’re accepted, so your handler should be idempotent: the same event may arrive more than once with the same X-Socialized-Event ID, which you can dedupe on. An endpoint receives only the events emitted after it was registered. Respond 2xx quickly and do the work asynchronously; a slow handler is a failed delivery.