Copy page

Documentation

Webhooks for Post Events

Subscribe to events to get real-time notifications when posts are published, scheduled, or fail. Webhooks are the right choice when you want to know about state changes without polling the API.

Creating a webhook

Code
curl -X POST https://api.omnisocials.com/v1/webhooks \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/omnisocials",
    "events": ["post.published", "post.failed"]
  }'

Response:

Code
{
  "data": {
    "id": "5f3b0c1e-9a2d-4e77-b1c4-8a2f6d9e0b12",
    "url": "https://your-app.com/webhooks/omnisocials",
    "events": ["post.published", "post.failed"],
    "is_active": true,
    "created_at": "2026-04-10T14:22:00Z",
    "secret": "a1b2c3d4e5f6...c7d8e9f0"
  },
  "message": "Webhook created. Save the secret - it will only be shown once."
}

The id is a UUID and the secret is a 64-character hex string returned exactly once on creation. Store the secret. You will need it to verify incoming webhook signatures.

Available events

Event	When it fires
post.scheduled	A post moves into the scheduled state
post.published	A post publishes successfully to at least one platform
post.failed	A post fails to publish on every selected platform

These are the only three valid events. Creating or updating a webhook with any other value (including a "*" wildcard) returns 400. There is no Social Inbox event (a new DM, comment, or mention) yet — poll GET /inbox/conversations instead.

Partial publishes fire post.published, not a separate event. When a post succeeds on some platforms and fails on others, the payload's data.status is "warning" and the per-platform outcomes are in data.targets (each with its own status). Inspect targets to see exactly which platforms succeeded or failed.

Payload shape

Code
{
  "id": "8c1e0a2b-4d5f-4a67-9b0c-1d2e3f4a5b6c",
  "type": "post.published",
  "created_at": "2026-04-10T14:22:00Z",
  "data": {
    "post_id": "123",
    "workspace_id": "456",
    "status": "posted",
    "post_type": "post",
    "scheduled_at": "2026-04-10T14:20:00Z",
    "published_at": "2026-04-10T14:22:00Z",
    "targets": [
      {
        "platform": "instagram",
        "status": "success",
        "native_post_id": "18023456789012345"
      },
      {
        "platform": "linkedin",
        "status": "failed",
        "native_post_id": null,
        "error": "The LinkedIn token has expired. Reconnect the account."
      }
    ]
  }
}

data.targets holds one entry per selected platform. native_post_id is the platform's own post ID (present when that platform succeeded); error appears only on a non-successful target. data.status is the overall post status (posted, warning for a partial success, or failed). Always branch on the top-level type before accessing data.

Verifying signatures

Every outbound webhook call is signed with HMAC-SHA256 using your webhook's secret. Each delivery carries these headers:

Header	Value
X-OmniSocials-Signature	t=<unix_timestamp>,v1=<hex_signature>
X-OmniSocials-Timestamp	The same unix timestamp, on its own
X-OmniSocials-Event	The event type (e.g. post.published)
X-OmniSocials-Webhook-Id	The webhook's ID
X-OmniSocials-Delivery	A unique ID per event, stable across retry attempts. Use it to deduplicate.

The signature is computed over `${timestamp}.${rawBody}` (the timestamp, a literal dot, then the raw JSON body), the same scheme Stripe uses. To verify: parse t and v1 out of the header, recompute the HMAC over timestamp.rawBody, and compare against v1. A mismatch means the request is not from OmniSocials. Reject it.

Code
import crypto from 'crypto'

function verifyWebhook(rawBody, signatureHeader, secret) {
  // signatureHeader looks like "t=1744294920,v1=abc123..."
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((kv) => kv.split('='))
  )
  const { t: timestamp, v1: signature } = parts
  if (!timestamp || !signature) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`, 'utf8')
    .digest('hex')

  // timingSafeEqual throws when lengths differ, so check first
  const sigBuf = Buffer.from(signature)
  const expBuf = Buffer.from(expected)
  if (sigBuf.length !== expBuf.length) return false

  return crypto.timingSafeEqual(sigBuf, expBuf)
}

Verify against the raw request body, before any JSON parsing or reserialization. Always compare with a constant-time function like timingSafeEqual. Optionally, reject deliveries whose t timestamp is more than a few minutes old to guard against replay. Keep that window at 5 minutes or more: the timestamp is set when the event is created and reused on retries, so a retried delivery arrives with the original timestamp.

Delivery and retries

• Respond with any 2xx within 10 seconds. That counts as delivered. Anything else (including a timeout after 10 seconds) counts as a failure. Do your processing after you respond, not before.
• Failed deliveries retry twice: the first retry after 2 seconds, the second after 5 more. Only 5xx, 429, and network errors are retried; any other 4xx fails immediately without a retry.
• Delivery is at-least-once. If your endpoint processed the event but the response timed out, the retry delivers a duplicate. Deduplicate on X-OmniSocials-Delivery; it stays the same across retries of one event.
• Ordering is not guaranteed. Deliveries fire asynchronously and concurrently; a retrying delivery can arrive after a newer event. Order on the payload's created_at.
• After the final failed attempt the event is dropped. It is not re-sent later, and there is no replay endpoint. The webhook records the failure: failure_count increments and last_failure (time, status, error) is stored; read both via GET /webhooks/:id. A webhook is never disabled automatically, so a recovered endpoint receives the next event normally. Reconcile missed events by polling GET /posts?status=.
• Requests come with User-Agent: OmniSocials-Webhooks/1.0 and follow up to 3 redirects.

Local testing. Webhook URLs must be publicly reachable. For local development, expose your dev server with a tunnel (for example cloudflared tunnel or ngrok http 3000) and register the tunnel URL as the webhook.

Managing webhooks

All webhook endpoints require the webhooks:manage scope on your API key.

Endpoint	Description
GET /webhooks	List all webhooks for this key
GET /webhooks/:id	Get a single webhook
PATCH /webhooks/:id	Update URL, events, or is_active (re-enabling resets failure_count)
DELETE /webhooks/:id	Delete a webhook
POST /webhooks/:id/rotate-secret	Rotate the signing secret

Rotating a secret immediately invalidates the old one. Update your verification code to use the new secret before rotating, or accept a short window of failed verifications.