Social Media API Webhooks Explained (2026)

You scheduled a post via API. Now what? Does your app sit there making requests every 30 seconds asking "did it publish yet?" Or does the API just tell you the moment something happens?

That second option is exactly what social media API webhooks do. And once you use them, polling feels embarrassing.

What are social media API webhooks?

Social media API webhooks are HTTP callbacks your server registers to receive automatic notifications when specific events occur. When a post publishes, fails, or gets a comment, the API sends an HTTP POST to your endpoint with the event data. No polling. No wasted requests. Your app reacts in real time.

This is the difference between checking your email every 5 minutes and having push notifications turned on.

Why native platform webhooks are painful to set up

Each platform handles event notifications differently, and none of them make it easy.

Meta (Instagram/Facebook) requires you to set up a Webhooks subscription through their Graph API, verify your endpoint via a challenge-response handshake, manage separate subscriptions per object type, and deal with app review before you can access certain events in production. The documentation alone is 11 pages long.

LinkedIn webhooks are only available on partner-approved integrations. Individual developers cannot access them without applying for LinkedIn's Partner Program, which takes weeks.

Twitter/X moved most webhook capabilities behind paid API tiers starting in 2023. Basic real-time event access now costs $100/month minimum.

The result: most developers end up polling. It works, but it burns through your rate limits and adds latency to anything time-sensitive like CMS sync, Slack notifications, or analytics pipelines.

How OmniSocials API webhooks work

OmniSocials takes a different approach. Instead of managing webhooks per platform, you register a single webhook endpoint with the OmniSocials API. It handles the platform-specific event subscriptions internally and delivers normalized event payloads to your URL.

One endpoint. All platforms. Consistent payload format.

Here are the events OmniSocials webhooks fire on:

• post.scheduled: post successfully queued for a future time
• post.published: post went live on one or more platforms
• post.failed: publishing error on one or more platforms (includes the error reason)
• post.approved: a post in an approval workflow was approved
• post.rejected: a post in an approval workflow was rejected

Every delivery has the same shape, whatever the platform (trimmed):

{
  "id": "5b0e7c1a-...",
  "type": "post.failed",
  "created_at": "2027-03-02T09:00:04.000Z",
  "data": {
    "post_id": 1019,
    "post_type": "Post",
    "scheduled_at": "2027-03-02T09:00:00.000Z",
    "published_at": "2027-03-02T09:00:04.000Z",
    "targets": [
      { "platform": "linkedin", "status": "success", "native_post_id": "urn:li:share:..." },
      { "platform": "bluesky", "status": "failed", "native_post_id": null, "error": "..." }
    ]
  }
}

targets lists one entry per platform, so a single event tells you exactly which networks worked, which failed, and why.

[Screenshot: OmniSocials webhook settings panel showing registered endpoints and event subscriptions]

Setting up your first webhook

The examples use the official SDKs for Node.js (npm install @omnisocials/sdk) and Python (pip install omnisocials). Both read your API key from OMNISOCIALS_API_KEY. You can also add a webhook in the dashboard under Settings > API.

Step 1: Register your endpoint

Create a webhook with your HTTPS target URL and the events you want to subscribe to (this is POST /v1/webhooks under the hood).

import { OmniSocials } from '@omnisocials/sdk';

const client = new OmniSocials(); // reads OMNISOCIALS_API_KEY

const { data: webhook } = await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/omnisocials',
  events: ['post.published', 'post.failed'],
});

console.log(webhook.id, webhook.secret); // the secret is shown only once

from omnisocials import OmniSocials

client = OmniSocials()  # reads OMNISOCIALS_API_KEY

webhook = client.webhooks.create(
    url="https://yourapp.com/webhooks/omnisocials",
    events=["post.published", "post.failed"],
)["data"]
# Save webhook["secret"]: you need it to verify incoming events

Save the secret returned in the response. It is only shown at creation, and you use it to verify that incoming requests actually come from OmniSocials. Lost it? client.webhooks.rotateSecret(id) (rotate_secret in Python) issues a new one.

Step 2: Handle incoming events

OmniSocials sends a POST request to your URL with a JSON body and an X-OmniSocials-Signature header in the form t=<unix>,v1=<hex>. The v1 value is an HMAC-SHA256, keyed with your secret, over the timestamp, a dot, and the raw request body ({t}.{rawBody}). Verify it against the raw body before you parse the JSON, and reject events more than 5 minutes old to stop replays.

The SDKs do all of that in one call:

// Express.js webhook handler
import express from 'express';
import { verifyWebhookSignature } from '@omnisocials/sdk';

const app = express();
const raw = express.raw({ type: 'application/json' });

app.post('/webhooks/omnisocials', raw, (req, res) => {
  let event;
  try {
    event = verifyWebhookSignature({
      payload: req.body, // raw Buffer: verify before parsing
      signature: req.get('X-OmniSocials-Signature') ?? '',
      secret: process.env.OMNISOCIALS_WEBHOOK_SECRET,
    });
  } catch {
    return res.status(400).send('Invalid signature');
  }

  switch (event.type) {
    case 'post.published':
      console.log(`Post ${event.data.post_id} is live`);
      // Update your database, trigger a Slack notification, etc.
      break;

    case 'post.failed':
      for (const t of event.data.targets) {
        if (t.status === 'failed') console.error(t.platform, t.error);
      }
      // Alert your team, retry logic, etc.
      break;
  }

  res.sendStatus(200);
});

import os
from flask import Flask, request
from omnisocials import WebhookVerificationError, verify_webhook_signature

app = Flask(__name__)

@app.post("/webhooks/omnisocials")
def handle_webhook():
    try:
        event = verify_webhook_signature(
            request.get_data(),  # the raw body, not request.json
            request.headers.get("X-OmniSocials-Signature", ""),
            os.environ["OMNISOCIALS_WEBHOOK_SECRET"],
        )
    except WebhookVerificationError:
        return "Invalid signature", 400

    if event["type"] == "post.published":
        print("Live:", event["data"]["post_id"])

    return "", 204

Not using an SDK? This is the same check by hand in Node.js:

import crypto from 'node:crypto';

function verifySignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const age = Math.floor(Date.now() / 1000) - Number(parts.t);
  if (!parts.t || !parts.v1 || age > 300) return false; // 5-minute tolerance

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

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Always respond with a 2xx status quickly. OmniSocials waits up to 10 seconds for an answer and makes up to 3 attempts in total (a first try, then retries after 2 and 5 seconds) on timeouts, network errors, 429, and 5xx responses. Any other 4xx answer is treated as final and not retried. The signature stays the same across retries, so do slow work in a background job and acknowledge right away.

Step 3: Test and manage your webhooks

You can list, update, or delete webhooks through the API at any time.

// List all registered webhooks
const { data: webhooks } = await client.webhooks.list();

// Pause one without deleting it
await client.webhooks.update(webhooks[0].id, { is_active: false });

// Delete a webhook
await client.webhooks.delete(webhooks[0].id);

Real-world use cases for social media webhooks

Webhooks open up automation patterns that polling just cannot support reliably.

Sync post status to your CMS. When a post publishes, mark it as "live" in your database automatically. No manual checks, no guessing.

Slack or Discord alerts on failures. When post.failed fires, send an immediate alert to your team's channel with the error reason. Catch broken OAuth tokens before they become a problem.

Analytics pipeline triggers. When a post publishes, kick off a job to start collecting engagement data after 24 hours. Chain it with the OmniSocials /v1/analytics/posts/{id} endpoint for a fully automated reporting workflow.

Client dashboards. If you're building an agency tool, surface real-time post status to clients without them needing to check the OmniSocials dashboard themselves.

OmniSocials vs native platform webhooks

The gap is most obvious when you need webhooks across multiple platforms. Getting post.published events from Instagram, LinkedIn, and X separately means three different integration setups, three different payload formats, and three different verification mechanisms. With OmniSocials, it's one.

Frequently Asked Questions

What is a social media API webhook?

A social media API webhook is an HTTP callback that fires automatically when a specific event occurs, such as a post publishing successfully, a post failing, or a comment being received. Instead of polling the API repeatedly, your server receives the event data as soon as it happens.

How do I create a webhook for social media posts?

With the OmniSocials API, you create a webhook by sending a POST request to https://api.omnisocials.com/v1/webhooks (or calling client.webhooks.create() in the SDKs) with your HTTPS endpoint URL and the event types you want to subscribe to. OmniSocials then sends a signed HTTP POST to your endpoint whenever those events fire.

What events can social media webhooks fire on?

Common social media webhook events include post.published, post.failed, and post.scheduled. OmniSocials adds post.approved and post.rejected for approval workflows, and normalizes events across all 13 supported platforms into a consistent payload format, so your handler code stays the same regardless of which platform triggered the event.

Are webhooks better than polling for social media APIs?

Yes. Polling means making API requests every few seconds or minutes to check for updates, which burns through rate limit quota and adds latency. Webhooks push the event to your server the moment it happens, with zero wasted requests and near-instant reaction time.

How do I verify a webhook is legitimate?

Verify webhooks using the shared secret returned when you register your endpoint. The OmniSocials API signs every webhook payload with an HMAC-SHA256 signature in the X-OmniSocials-Signature header (t=<unix>,v1=<hex>, computed over {t}.{rawBody}). Compute the expected signature on your server using your webhook secret, compare it to the header value, and reject events older than 5 minutes. The SDK functions verifyWebhookSignature (Node.js) and verify_webhook_signature (Python) do this for you.

The full webhook API reference, including retry behavior, payload schemas, and event filtering, is at docs.omnisocials.com. If you want to test without setting up a public endpoint first, tools like Webhook.site or ngrok let you inspect incoming payloads locally before writing a single line of handler code.

Sources

• Webhook.site: Free tool for inspecting and debugging incoming webhook payloads
• Meta Webhooks Documentation: Official reference for Facebook and Instagram Graph API webhooks
• ngrok Documentation: Tunnel local servers to public URLs for webhook development and testing
• HMAC Authentication (Wikipedia): Background on HMAC-SHA256 signature verification used in webhook security
• OmniSocials API Docs: Full reference for the OmniSocials REST API including webhook endpoints