Webhooks
A Buzzmark webhook sends a signed POST to your server when a post is scheduled, goes out, fails or is approved, or when an account needs reconnecting.
Owners and editors add them in Settings, under Developers, on every plan. Each event carries ids, statuses and times, never a post's words or a person's name.
Failed deliveries are retried with the same event id, so dedupe on it.
Add a webhook
A webhook runs a Slack alert, a CRM update or a report when something happens, without polling the API.
1. In Buzzmark, open Settings and go to Developers.
2. Under Webhooks, paste your server's address into Endpoint, name it and pick its Events.
3. Press Add webhook, then Copy the signing secret. Buzzmark shows it once.
4. Press Send test event on the new row: your endpoint gets a
webhook.testevent, and Buzzmark says what it answered.
Note: The address must be public https. Buzzmark refuses one that points to a private network, when you save it and again before every delivery.
Events
| Event | Sent when | data holds |
|---|---|---|
| post.scheduled | A post is scheduled or moved to a new time. | post_id, social_set_id, status, scheduled_at, accounts |
| post.published | A post went out on every account. | post_id, social_set_id, status, scheduled_at, accounts |
| post.partially_failed | A post went out on some accounts and failed on others. | post_id, social_set_id, status, scheduled_at, accounts |
| post.failed | A post didn't go out. | post_id, social_set_id, status, scheduled_at, accounts |
| post.unconfirmed | A post's time passed and no platform confirmed it went out. | post_id, social_set_id, status, scheduled_at, accounts |
| account.needs_reconnect | An account needs reconnecting before its next post can go out. | account_id, platform, social_set_ids |
| buzz.approved | A post waiting for approval was approved, by a teammate or a client. | post_id, social_set_id, status, scheduled_at, accounts, by |
| buzz.changes_requested | A post waiting for approval was sent back, by a teammate or a client. | post_id, social_set_id, status, scheduled_at, accounts, by |
Every event carries ids, statuses and times, never a post's words or a person's name. Read the rest with GET /posts/{id}.
post.published
{
"id": "evt_7d1f0c2a9b4e4f6c8a3b5d9e1f2a4c6b",
"type": "post.published",
"created": 1763215200,
"data": {
"post_id": 408,
"social_set_id": 12,
"status": "published",
"scheduled_at": "2026-11-15T14:00:00Z",
"accounts": [
{
"account_id": 51,
"platform": "linkedin"
}
]
}
}Check a webhook's signature
| Header | Value |
|---|---|
| Buzzmark-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" with your signing secret> |
| Buzzmark-Event-Id | evt_…, the same on every attempt of one event |
| Buzzmark-Event-Type | post.published, account.needs_reconnect … |
| Buzzmark-Delivery-Id | dlv_…, one per endpoint and event |
| Buzzmark-Attempt | 1 to 6 |
| Buzzmark-Timestamp | the same unix seconds as t |
Buzzmark-Signature is an HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your signing secret. Check it on the raw body, before parsing it, and refuse an old one. This checker needs nothing but Node:
verify-buzzmark.js
import { createHmac, timingSafeEqual } from "node:crypto";
// Checks a Buzzmark webhook. Pass the raw body exactly as it arrived (a string, before JSON.parse),
// the Buzzmark-Signature header and your endpoint's signing secret. Returns the event, or throws.
export function verifyBuzzmarkWebhook(rawBody, signatureHeader, secret, now = Date.now()) {
const parts = {};
for (const piece of String(signatureHeader ?? "").split(",")) {
const at = piece.indexOf("=");
if (at > 0) parts[piece.slice(0, at).trim()] = piece.slice(at + 1).trim();
}
const t = Number(parts.t);
if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) throw new Error("Malformed Buzzmark-Signature header");
if (Math.abs(Math.floor(now / 1000) - t) > 300) throw new Error("Signature is more than 5 minutes old");
const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest();
if (!timingSafeEqual(expected, Buffer.from(parts.v1, "hex"))) throw new Error("Signature doesn't match");
return JSON.parse(rawBody);
}
In an Express app, read the body as text so it reaches the checker byte for byte:
server.js
import express from "express";
import { verifyBuzzmarkWebhook } from "./verify-buzzmark.js";
const app = express();
app.post("/buzzmark", express.text({ type: "application/json" }), (req, res) => {
let event;
try {
event = verifyBuzzmarkWebhook(req.body, req.get("Buzzmark-Signature"), process.env.BUZZMARK_WEBHOOK_SECRET);
} catch {
return res.sendStatus(400);
}
res.sendStatus(200); // answer within 10 seconds, then do the work
// event.id is the same on every retry: skip one you've already handled.
});
Deliveries and retries
| Rule | Value |
|---|---|
| A delivery counts when your endpoint answers | a 2xx within 10 seconds. A redirect is a failure and isn't followed. |
| A failed delivery is tried again after | 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours: 6 attempts in all, each with the same event id. A test event is sent once. |
| An endpoint turns itself off after | 20 failed deliveries in a row. The owner gets a notification, and turning it back on starts the count again. |
| The sample verifier refuses a signature older than | 5 minutes. |
| Settings, Developers keeps each delivery for | 30 days: its status, attempt, your endpoint's HTTP status and how long it took. Never the body your endpoint answered. |
| Webhooks per organization | 10, added by an owner or an editor. |
A retry can arrive after a later event, and the same event can arrive twice. Keep the ids you've handled and skip one you've seen.
Webhooks are added, changed and deleted in Settings only, not through the API. To change a signing secret, delete the webhook and add it again.
Where to next
- n8n and Make
n8n and Make call the Buzzmark API from n8n's HTTP Request node or Make's HTTP module, with your key in the Authorization header.
- Check and schedule posts
POST /posts/validate checks a post against each account's platform rules and saves nothing; POST /posts and POST /posts/bulk run the same check, then schedule.
- Errors and limits
A Buzzmark API refusal is JSON with a code, a message, whether a retry may work, and a request id, and its HTTP status matches the code.
- Notifications
Buzzmark tells you what happened to your posts in two places: the bell in the top bar and email.