Guide
Webhooks
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.
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.
{
"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.
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));
}import hashlib, hmac, time
def verify(raw_body: bytes, headers, secret: str) -> bool:
timestamp = headers.get("X-Socialit-Timestamp")
signature = headers.get("X-Socialit-Signature")
if not timestamp or not signature or abs(time.time() - int(timestamp)) > 300:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature, expected)<?php
function verify(string $rawBody, array $headers, string $secret): bool {
$timestamp = $headers['X-Socialit-Timestamp'] ?? null;
$signature = $headers['X-Socialit-Signature'] ?? null;
if (!$timestamp || !$signature || abs(time() - (int) $timestamp) > 300) return false;
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($expected, $signature);
}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}/testsends a test event of the type you choose.GET /v1/webhooks/{id}/deliverieslists recent deliveries with status codes and response bodies.POST /v1/webhooks/deliveries/{id}/redeliversends one again;POST /v1/webhooks/{id}/retry-failedretries all failed ones.POST /v1/webhooks/{id}/reset-secretrotates the signing secret.