Skip to main content

Webhooks

PostBoost sends real-time HTTP POST notifications to your endpoint when key events occur. No polling needed.

Setup​

Register your webhook URL in Settings → Webhooks in the dashboard. PostBoost will POST a JSON payload to your URL when an event fires.

Events​

EventFired when
post.scheduledA post is successfully scheduled
post.publishedA post publishes successfully to all platforms
post.failedA post fails to publish on one or more platforms
post.approvedA post in review is approved

Payload format​

{
  "event": "post.published",
  "workspace_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "post": {
    "uuid": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "status": "published",
    "scheduled_at": "2026-06-01T10:00:00Z",
    "published_at": "2026-06-01T10:00:03Z",
    "accounts": [
      { "provider": "instagram", "name": "myhandle" }
    ]
  },
  "timestamp": "2026-06-01T10:00:03Z"
}

Responding to webhooks​

Your endpoint must return a 2xx HTTP status within 5 seconds. PostBoost will retry failed deliveries up to 3 times with exponential backoff.

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook/postboost", methods=["POST"])
def handle_webhook():
    payload = request.get_json()
    event = payload.get("event")

    if event == "post.published":
        post_uuid = payload["post"]["uuid"]
        # Handle successful publish...

    return jsonify({"ok": True}), 200

Security​

Verify that webhook requests genuinely come from PostBoost by checking the X-PostBoost-Signature header (coming soon). For now, use a secret URL path as an additional layer of security.

Using webhooks with AI agents​

Webhooks are ideal for agentic workflows:

  1. Agent creates a post via POST /posts with schedule: true
  2. PostBoost fires post.published when it goes live
  3. Your webhook handler triggers the next step in the agent pipeline (analytics check, follow-up content generation, etc.)

This gives you fully asynchronous, event-driven social publishing — no polling, no blocking calls.

Next steps​