Introducing Webhooks: Real-Time Notifications for the SocialRails API

We just shipped webhooks for the SocialRails API. You can now receive instant HTTP notifications whenever something happens in your workspace — a post gets published, fails, or is scheduled.

No more polling. No more guessing. Your systems get notified the moment something changes.

Why Webhooks?

If you've been using the SocialRails API to schedule posts, you've probably built some kind of polling loop to check whether posts were published. That works, but it's wasteful and slow.

With webhooks, SocialRails pushes events to your server as they happen. You get:

• Instant feedback — know the moment a post goes live or fails
• Less API usage — no need to repeatedly call GET /posts to check status
• Simpler integrations — trigger downstream workflows automatically

Supported Events

We currently support three event types:

You choose which events each webhook receives, so you only get what you need.

How It Works

1. Register a webhook

Send a POST request with your HTTPS endpoint and the events you want:

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

You'll get back a signing secret. Save it — this is the only time you'll see it.

2. Receive events

When an event occurs, we send an HTTP POST to your endpoint with a JSON payload:

{
  "event": "post.published",
  "timestamp": "2026-03-04T14:30:00Z",
  "data": {
    "post_id": "abc-123",
    "workspace_id": "def-456",
    "platform": "twitter",
    "status": "published"
  }
}

Every request includes these headers:

• X-SocialRails-Signature — HMAC-SHA256 signature for verification
• X-SocialRails-Timestamp — Unix timestamp (seconds) for replay protection
• X-SocialRails-Event — The event type

3. Verify the signature

Always verify that webhooks are actually coming from SocialRails. Here's how in Node.js:

const crypto = require('crypto');
 
function verifyWebhook(payload, signature, timestamp, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');
 
  const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
  const untrusted = Buffer.from(signature, 'utf8');
 
  return crypto.timingSafeEqual(trusted, untrusted);
}

We recommend rejecting any request with a timestamp older than 5 minutes to prevent replay attacks.

Built for Reliability

Webhooks can be tricky when networks are involved, so we built in safeguards:

• Automatic retries — if your endpoint returns a 5xx error or is unreachable, we retry once after 2 seconds
• 10-second timeout — we won't hold connections open forever
• Delivery logging — every attempt is logged with status, HTTP response code, and latency so you can debug issues
• HTTPS only — all webhook URLs must use HTTPS
• SSRF protection — we block private and internal IP addresses

Use Cases

Here are some things you can build with webhooks:

• Slack notifications — get a message in your team channel when a post goes live or fails
• Analytics pipelines — track publishing success rates in real time
• Retry workflows — automatically reschedule failed posts with modified content
• Client reporting — notify clients the moment their scheduled content is published
• n8n / Zapier automations — trigger any downstream workflow when events fire

Getting Started

Webhooks are available now on all plans with API access. You can manage them from the dashboard under API Settings, or use the API directly.

To get started:

1. Create an API key with the webhooks scope in your dashboard
2. Register a webhook endpoint
3. Start receiving events

Full technical details, including Python examples and payload schemas, are in our webhook documentation.

SDK Support

Both our official SDKs already support webhooks:

JavaScript:

 
const client = new SocialRails({ apiKey: 'sr_live_...' });
 
const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhooks',
  events: ['post.published', 'post.failed'],
});
 
console.log(webhook.secret); // Save this!

Python:

from socialrails import SocialRails
 
client = SocialRails(api_key="sr_live_...")
 
webhook = client.webhooks.create(
    url="https://your-app.com/webhooks",
    events=["post.published", "post.failed"],
)
 
print(webhook["secret"])  # Save this!

What's Next

This is the first version of our webhook system. We're planning to add:

• Delivery history in the dashboard — view and debug every webhook delivery attempt right from the UI
• More event types — account-level events, analytics milestones, and more
• Webhook testing tools — send test events from the dashboard to verify your integration

Have feedback or ideas for new events? We'd love to hear from you — reach out on X or through the dashboard.