Skip to content

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"]
  }' | jq

reach 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" }
}
EventFires when
publication.target.publisheda single target goes live (its warnings list the steps that didn’t go through, each a { step, detail }: the lifecycle)
publication.target.faileda single target fails (its failure says why, as a target’s does: the lifecycle)
publication.target.removed_remotelya live post is observed to have been deleted manually on the platform
publication.completeda publication reaches a terminal state (done / partial / failed)
connection.reauth_requireda 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.

The API is the product; the dashboard is its best-known client.