Webhook

What is a webhook?

A webhook is an HTTP-based callback mechanism: a server-to-server message that fires when a specific event happens. The mechanic: you (the consumer) register a URL on the provider's system; when the registered event occurs, the provider's server makes an HTTP POST request to your URL with the event data in the body. Webhooks are also called 'reverse APIs' because they invert the typical pattern — instead of you asking the API for new data, the API tells you when there's something new.

In social media context, webhooks deliver events like: post.published (your scheduled post went live), post.failed (the post hit an error during publishing), post.token_expired (the user's OAuth token needs reconnect), comment.received (someone commented on a post), follower.gained / follower.lost (audience changes). The receiver's job is to handle each event appropriately — write to a database, ping Slack, retry, etc.

Why webhooks beat polling

Three reasons. First, latency — webhooks deliver events within seconds; polling delivers them within whatever interval you chose (typically 30-60 seconds, sometimes minutes). Second, cost — webhooks consume zero quota until events happen; polling burns quota constantly even when nothing's new. Third, scale — polling 1,000 posts every 30 seconds is 2,000 API calls per minute, hitting rate limits; webhooks for the same 1,000 posts is zero baseline traffic plus events as they happen.

For social media specifically, polling is also problematic because it ages OAuth tokens unnecessarily — every poll is an API call, and most platforms refresh token expiry on inactive periods. Active polling on inactive posts can paradoxically trigger token expiration faster than no polling.

How to consume a webhook

Five-step pattern. (1) Expose an HTTPS endpoint on your server (e.g., POST /webhook/codivupload). (2) Register the URL in the provider's dashboard or via API. (3) Store the webhook signing secret the provider gives you. (4) On each incoming POST, verify the request signature (typically HMAC-SHA256 of the body, sent in a header like X-Signature). (5) Process the event, respond with 200 OK quickly (within seconds — most providers retry on slow responses or non-200 responses).

Key gotcha: webhooks must be idempotent. Providers retry on failures, so the same event can arrive 2-3 times. Track event IDs in a database and skip duplicates.

Sample webhook payload from CodivUpload — post.published event

json

// POST https://your-server.com/webhook/codivupload
// Headers:
//   X-CodivUpload-Signature: hmac-sha256-hex-of-body
//   X-CodivUpload-Event: post.published
{
  "event": "post.published",
  "id": "evt_a8b3c7e2",
  "timestamp": "2026-05-08T14:00:42Z",
  "data": {
    "post_id": "post_k8m2v9x1",
    "profile_name": "main",
    "platform": "instagram",
    "platform_post_id": "17891234567890",
    "platform_post_url": "https://instagram.com/p/Cabc123/",
    "scheduled_at": "2026-05-08T14:00:00Z",
    "published_at": "2026-05-08T14:00:42Z"
  }
}

// Verify signature in your handler:
import { createHmac } from 'crypto';
function verify(body: string, signature: string, secret: string) {
  const computed = createHmac('sha256', secret).update(body).digest('hex');
  return computed === signature;
}

Frequently asked questions