Webhooks

Receive real-time notifications when post status changes, accounts disconnect, or errors occur.

Configure Webhooks

POST /v1/webhooks/settings

Request

{
  "url": "https://yourapp.com/webhooks/socialapi",
  "events": ["post.published", "post.failed", "account.disconnected"]
}

Events

Webhook Payload

{
  "event": "post.published",
  "timestamp": "2026-01-15T10:00:00Z",
  "data": {
    "postId": "post_abc123",
    "platform": "instagram",
    "platformPostId": "17841400123456789",
    "platformPostUrl": "https://instagram.com/p/ABC123",
    "status": "published"
  }
}

Verifying Webhooks

Each webhook request includes a X-SocialSyncerAPI-Signature header. Verify it to ensure the request came from SocialSyncerAPI:

Python

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your webhook handler
@app.post("/webhooks/socialapi")
async def handle_webhook(request):
    payload = await request.body()
    signature = request.headers.get("X-SocialSyncerAPI-Signature")

    if not verify_webhook(payload.decode(), signature, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    data = json.loads(payload)
    event = data["event"]

    if event == "post.published":
        # Handle successful publish
        pass
    elif event == "post.failed":
        # Handle failure — maybe retry
        pass

    return {"ok": True}

Node.js

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post("/webhooks/socialapi", (req, res) => {
  const signature = req.headers["x-socialapi-signature"];
  if (!verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, data } = req.body;
  if (event === "post.published") {
    console.log("Post published:", data.platformPostUrl);
  }

  res.json({ ok: true });
});

Test Webhooks

POST /v1/webhooks/test

Send a test webhook to verify your endpoint is working:

curl -X POST https://api.socialsyncerapi.com/v1/webhooks/test \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"event": "post.published"}'

Best Practices