Copy page

Guides

Webhooks

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
{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/omnisocials",
  "events": ["post.published", "post.failed"],
  "secret": "whsec_..."
}

The secret is returned exactly once on creation. Store it. 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
post.partially_published	A post publishes to some but not all selected platforms

Subscribe to all events by passing "events": ["*"].

Payload shape

Code
{
  "id": "evt_abc123",
  "type": "post.published",
  "created_at": "2026-04-10T14:22:00Z",
  "data": {
    "post_id": "123",
    "status": "posted",
    "platforms": ["instagram", "linkedin", "linkedin_page"],
    "urls": {
      "instagram": "https://instagram.com/p/xxx",
      "linkedin": "https://linkedin.com/posts/xxx",
      "linkedin_page": "https://linkedin.com/company/xxx/posts/xxx"
    }
  }
}

The data field varies by event type. Always branch on type before accessing data properties.

Verifying signatures

Every outbound webhook call is signed with HMAC-SHA256 using your webhook's secret. The signature appears in the X-OmniSocials-Signature header as sha256=<hex>.

To verify: compute HMAC-SHA256 of the raw request body using your secret, and compare against the header value. A mismatch means the request is not from OmniSocials. Reject it.

Code
import crypto from 'crypto'

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  )
}

Always compare with a constant-time function like timingSafeEqual. Never use string equality on secrets.

Managing webhooks

Endpoint	Description
GET /webhooks	List all webhooks for this key
GET /webhooks/:id	Get a single webhook
PUT /webhooks/:id	Update URL or events
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.