Webhooks
PostBoost sends an HTTP request to your endpoint when something happens in a workspace. No polling needed.
Setup
Add a webhook in Settings → Webhooks in the dashboard: the callback URL, the HTTP method, the content type, the events to send, an optional secret (used to sign deliveries) and the maximum number of delivery attempts.
Subscribe from code (n8n, Zapier, Make)
Automation tools can register their own webhook with the API (workspace admins; scoped keys need the webhooks ability):
curl -X POST https://postboost.co/app/api/$WORKSPACE/webhooks/subscriptions \
-H "Authorization: Bearer $POSTBOOST_API_TOKEN" -H "Content-Type: application/json" \
-d '{"callback_url":"https://n8n.example.com/webhook/abc","events":["post.published","post.publishing_failed"],"source":"n8n"}'
The response carries the subscription uuid and a secret, returned only once, that signs every delivery. Subscriptions send JSON POST requests and retry up to 3 times. Only public https:// URLs are accepted. GET /{workspaceUuid}/webhooks/subscriptions lists the workspace's webhooks, and DELETE /{workspaceUuid}/webhooks/subscriptions/{uuid} removes one.
Events
| Event | Fired when | Deliveries |
|---|---|---|
post.created | A post is created | One per post |
post.updated | A post is edited | One per post |
post.scheduled | A post is scheduled, queued or set to publish now | One per post |
post.published | A post went live on one account | One per account |
post.publishing_failed | Publishing to one account failed | One per account |
post.published_all | Publishing finished for every account of the post | One per post |
post.deleted | A post is deleted | One per post |
account.added | A social account is connected | One per account |
account.updated | A social account is updated | One per account |
account.deleted | A social account is removed | One per account |
account.token_expiring | An account's connection expires in 7, 3 or 1 days (once per threshold) | One per account and threshold |
account.disconnected | The network revoked or expired an account's access; it must be reconnected | One per account |
inbox.draft.created | An agent or integration drafted an inbox reply through the API; it waits for approval | One per draft |
inbox.draft.sent | A person approved a reply draft and it was posted on the network | One per draft |
Payload format
Every delivery has the same envelope: the event name, a delivery id (one per event; the same id is sent again on every retry and manual resend, so de-duplicate on it), occurred_at (ISO 8601, UTC), the workspace_uuid the event belongs to, and the event data. The OpenAPI spec describes it as the WebhookEnvelope schema, with one entry per event under webhooks.
{
"event": "post.publishing_failed",
"id": "4f1d9c2a-7b3e-4c8a-9e21-0d5f6a7b8c9d",
"occurred_at": "2026-10-12T10:00:03+00:00",
"workspace_uuid": "7c4c85c3-ded1-4e3c-889c-4626438bb8ba",
"data": {
"id": 1234,
"uuid": "9f2c1b7e-4a51-4d0e-9a51-6b7d9f0e2c11",
"status": "failed",
"accounts": [ { "id": 12, "uuid": "…", "provider": "facebook_page", "…": "…" } ],
"versions": [ { "account_id": 0, "is_original": true, "content": [ { "body": "Our API 1.9 is live.", "media": [] } ] } ],
"tags": [],
"scheduled_at": "2026-10-11 10:00:00",
"published_at": null,
"created_at": "2026-10-11 09:58:12",
"trashed": false,
"account": {
"id": 12,
"uuid": "2b0c7f8a-1d3e-4c55-8f0a-3e9d2b7c6a10",
"name": "PostBoost",
"provider": "facebook_page",
"authorized": true,
"external_url": null,
"publish_status": "failed",
"published_parts": 0,
"errors": [
"Facebook: (#200) Permissions error (code 200)",
{
"platform": "facebook_page",
"code": "200",
"message": "(#200) Permissions error",
"raw": { "error": { "message": "(#200) Permissions error", "type": "OAuthException", "code": 200, "fbtrace_id": "A1b2C3" } }
}
]
}
}
}
datais the post exactly asGET /{workspaceUuid}/posts/{postUuid}returns it. Post times are UTC, formattedY-m-d H:i:s.data.accountis the account the delivery is about. A post with three accounts sends threepost.published(orpost.publishing_failed) deliveries, told apart bydata.account.id.data.account.external_urlis the URL of the live post on the network once it is published.data.account.errorsexplains a failure. When the network returned an error body, the first entry is a readable line ("<Network>: <message> (code <code>)") and the second holds the network's code, message and original response inraw. Other failures are a single readable string.- Account events (
account.*) carry the account indata. - Two empty values keep an older shape in webhook payloads: a post content item without a link has
url: ""(the REST API returnsnull), and an account without provider data hasdata: [](the REST API returns{}). Treat""likenulland[]like{}. - Inbox events (
inbox.*) carry the reply draft indata, exactly asGET /{workspaceUuid}/inbox/drafts/{id}returns it (only when the inbox API is on). See Inbox. account.token_expiringaddsexpires_at,days_left,threshold(7, 3 or 1) andreconnect_urlto the account;account.disconnectedaddsreconnect_url. See Connection health.
Headers
| Header | Value |
|---|---|
Content-Type | The content type set on the webhook |
X-Request-Source | PostBoost |
X-Signature | HMAC-SHA256 of the raw request body, hex encoded, keyed with the webhook secret. Only sent when the webhook has a secret. |
X-PostBoost-Workspace | UUID of the workspace the event belongs to |
De-duplicate on the envelope's id (retries and manual resends repeat it). For post events, data.account.provider_post_id is the network's own ID of the published post and data.account.external_url links to it; both are null until the post is live.
Verifying signatures
Compute the HMAC-SHA256 of the raw request body with your webhook secret and compare it with X-Signature in constant time.
import hmac, hashlib
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = b"your-webhook-secret"
@app.route("/webhook/postboost", methods=["POST"])
def handle_webhook():
expected = hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Signature", "")):
abort(401)
payload = request.get_json()
if payload["event"] == "post.publishing_failed":
account = payload["data"]["account"]
print(f"{account['name']}: {account['errors'][0]}")
return {"ok": True}, 200
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/webhook/postboost", express.raw({ type: "*/*" }), (req, res) => {
const expected = crypto.createHmac("sha256", process.env.POSTBOOST_WEBHOOK_SECRET).update(req.body).digest("hex");
const given = req.get("X-Signature") ?? "";
if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
return res.sendStatus(401);
}
const payload = JSON.parse(req.body.toString("utf8"));
// …
res.status(200).json({ ok: true });
});
Responding and retries
- Answer with
200,201or202. Any other status (including204) or a network error counts as a failed delivery. - A failed delivery is retried until the webhook's maximum number of attempts is reached, waiting 2, 4, 8, … minutes between attempts.
- Deliveries and their responses are listed per webhook in Settings → Webhooks.
- Process deliveries idempotently: a retry carries the same body.
Using webhooks with AI agents
- The agent creates a post via
POST /{workspaceUuid}/posts(send anIdempotency-Keyso retries never create a second post). - PostBoost sends
post.publishedorpost.publishing_failedfor each account. - Your handler triggers the next step: analytics check, a fix and
POST /posts/retry/{postUuid}/{accountUuid}, or a follow-up post.
Next steps
- Error Handling — idempotent retries and guardrail errors
- Agent Guardrails — dry runs, duplicate guard and daily caps
- API Reference — Create Post — create posts that trigger webhook events