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

Event	Fired when
post.scheduled	A post is successfully scheduled
post.published	A post publishes successfully to all platforms
post.failed	A post fails to publish on one or more platforms
post.approved	A 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": "2025-06-01T10:00:00Z",
    "published_at": "2025-06-01T10:00:03Z",
    "accounts": [
      { "provider": "instagram", "name": "myhandle" }
    ]
  },
  "timestamp": "2025-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.