Skip to main content

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​

EventFired whenDeliveries
post.createdA post is createdOne per post
post.updatedA post is editedOne per post
post.scheduledA post is scheduled, queued or set to publish nowOne per post
post.publishedA post went live on one accountOne per account
post.publishing_failedPublishing to one account failedOne per account
post.published_allPublishing finished for every account of the postOne per post
post.deletedA post is deletedOne per post
account.addedA social account is connectedOne per account
account.updatedA social account is updatedOne per account
account.deletedA social account is removedOne per account
account.token_expiringAn account's connection expires in 7, 3 or 1 days (once per threshold)One per account and threshold
account.disconnectedThe network revoked or expired an account's access; it must be reconnectedOne per account
inbox.draft.createdAn agent or integration drafted an inbox reply through the API; it waits for approvalOne per draft
inbox.draft.sentA person approved a reply draft and it was posted on the networkOne 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" } }
}
]
}
}
}
  • data is the post exactly as GET /{workspaceUuid}/posts/{postUuid} returns it. Post times are UTC, formatted Y-m-d H:i:s.
  • data.account is the account the delivery is about. A post with three accounts sends three post.published (or post.publishing_failed) deliveries, told apart by data.account.id.
  • data.account.external_url is the URL of the live post on the network once it is published.
  • data.account.errors explains 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 in raw. Other failures are a single readable string.
  • Account events (account.*) carry the account in data.
  • Two empty values keep an older shape in webhook payloads: a post content item without a link has url: "" (the REST API returns null), and an account without provider data has data: [] (the REST API returns {}). Treat "" like null and [] like {}.
  • Inbox events (inbox.*) carry the reply draft in data, exactly as GET /{workspaceUuid}/inbox/drafts/{id} returns it (only when the inbox API is on). See Inbox.
  • account.token_expiring adds expires_at, days_left, threshold (7, 3 or 1) and reconnect_url to the account; account.disconnected adds reconnect_url. See Connection health.

Headers​

HeaderValue
Content-TypeThe content type set on the webhook
X-Request-SourcePostBoost
X-SignatureHMAC-SHA256 of the raw request body, hex encoded, keyed with the webhook secret. Only sent when the webhook has a secret.
X-PostBoost-WorkspaceUUID 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, 201 or 202. Any other status (including 204) 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​

  1. The agent creates a post via POST /{workspaceUuid}/posts (send an Idempotency-Key so retries never create a second post).
  2. PostBoost sends post.published or post.publishing_failed for each account.
  3. Your handler triggers the next step: analytics check, a fix and POST /posts/retry/{postUuid}/{accountUuid}, or a follow-up post.

Next steps​