Skip to content
Docs

Guide

Receive signed events for posts, accounts, the inbox, messaging, ads and billing, verify their signatures and handle retries.

Updated Oct 14, 2026

Webhooks send a POST request to your URL when something happens in your workspace. Create endpoints in Manage → Webhooks or with the Webhooks API (MCP toolset webhooks), and subscribe to every event or a list.

Terminal
curl -X POST https://api.socialit.com/v1/webhooks \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production", "url": "https://your-app.com/socialit/webhooks", "events": ["post.published", "post.failed", "message.received"] }'

The response includes the signing secret (or bring your own with secret). profile_ids limits an endpoint to events of some profiles; all_events: true subscribes to everything, including event types added later.

Payload

Every delivery has the same envelope; data depends on the event type.

JSON
{
  "id": "evt_9Qw2Lm4Rt6Yp1Xn3Vb8Kd5SzHc2",
  "object": "event",
  "type": "post.published",
  "created_at": "2026-10-14T09:00:04.512Z",
  "workspace_id": "ws_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
  "test": false,
  "data": {
    "post": {
      "object": "post",
      "id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd",
      "status": "published",
      "postings": [{ "object": "posting", "platform": "instagram", "status": "published", "url": "https://www.instagram.com/p/…" }]
    }
  }
}

Headers: X-Socialit-Signature, X-Socialit-Timestamp, X-Socialit-Event (the type) and X-Socialit-Delivery (the delivery ID).

Event types

Socialit emits about 90 event types across posts, accounts, the inbox, contacts and automations, ads, analytics and billing. The Webhook events reference lists every one with its payload, generated from the same catalog the API validates subscriptions against (GET /v1/events/names). GET /v1/events is the event log: the same payloads, kept for replay and debugging.

Verify the signature

Every delivery has two headers:

  • X-Socialit-Timestamp: Unix time in seconds when the delivery was signed.
  • X-Socialit-Signature: hex HMAC-SHA256 of ${timestamp}.${body} with your endpoint’s secret.

Compute the HMAC over the raw request body, compare in constant time, and reject timestamps older than five minutes to stop replays.

JavaScript
import crypto from 'node:crypto';

export function verify(rawBody, headers, secret) {
  const timestamp = headers['x-socialit-timestamp'];
  const signature = headers['x-socialit-signature'];
  if (!timestamp || !signature || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Responding and retries

Answer with any 2xx status quickly, and do slow work after responding. Socialit retries failed deliveries after 5 minutes, 30 minutes, 2 hours and 5 hours, then every 12 hours, up to 11 attempts. An endpoint that keeps failing for 3 days is disabled automatically.

Deliveries can arrive more than once and out of order: use the event id to deduplicate and created_at to order.

Tools

  • POST /v1/webhooks/{id}/test sends a test event of the type you choose.
  • GET /v1/webhooks/{id}/deliveries lists recent deliveries with status codes and response bodies.
  • POST /v1/webhooks/deliveries/{id}/redeliver sends one again; POST /v1/webhooks/{id}/retry-failed retries all failed ones.
  • POST /v1/webhooks/{id}/reset-secret rotates the signing secret.