Reviewed 2026-11-11 · API version 2026-11-09 · Read Markdown
Customer webhooks
Outgoing event delivery for your workspace. Register an HTTPS endpoint, verify the one-time signing secret, and receive signed events with bounded retries.
Register an endpoint
curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
$BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
- The signing secret (
whsec_…) is returned once: in the first successful creation response. Store it; an idempotent replay of the same creation returns the endpoint without the secret, and it cannot be shown again. - Destinations must be HTTPS, publicly resolvable, and free of embedded credentials. Requests to private, loopback, link-local (including cloud metadata), unique-local and multicast addresses are refused before any connection is made, and redirects are never followed.
- Registration enqueues a targeted
webhook.verificationevent for that endpoint, independent of itseventTypesfilter. Ordinary events flow only after your endpoint answers the verification with 2xx.
Verifying deliveries
Every request carries:
| Header | Meaning |
|---|---|
x-publisher-event-id | Stable event ID: identical across retries and replays |
x-publisher-event-type | Event type, e.g. post.published |
x-publisher-timestamp | Unix seconds |
x-publisher-signature | t=<ts>,v1=<hex> |
The signature is HMAC-SHA256 over ${t}.${event_id}.${raw_body} using your
signing secret. Verify with a ±300 second tolerance and reject replays outside
it. Node example:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, headers, rawBody) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
if (!m) return false;
const [t, v1] = [Number(m[1]), m[2]];
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
.digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
Always verify against the raw request body before parsing.
Event envelope
{
"id": "0192d0d0-0000-7000-8000-00000000000f",
"type": "post.published",
"createdAt": "2026-11-09T12:00:01Z",
"apiVersion": "2026-11-09",
"data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
Initial event catalog (extensible; eventTypes filters at registration):
webhook.verification: challenge payload; answer 2xx to activate the endpointpost.published: one destination confirmed with a native receiptdelivery.failed: one destination failed terminallydelivery.requires_action: consent/reconnection/late-review required
Aggregate post outcomes (post.partially_published, post.failed) are not
emitted yet; they are documented here only once a producer exists, so don't
rely on them. Subscribe to the per-destination events above and derive batch
state from the post's delivery outcomes.
Retries, replay and disabling
- Attempts: immediately, then +1m, +5m, +30m, +2h, +8h. Retries reuse the same event ID and byte-identical body so you can deduplicate safely.
- 2xx = delivered. 429/5xx/timeouts retry. Other 4xx fail permanently for that event (fix the endpoint, then replay).
- 410 Gone disables the endpoint: no further events are enqueued to it.
- Operator-authorized replay through the internal webhook service re-sends an event with its original ID. An actively-leased in-flight attempt is never yanked; replay reports that the event is busy and can be retried shortly.
Operational notes
- Delivery diagnostics store only safe outcome codes: never your secret, signatures, request headers or response bodies. Payloads are additionally sanitized: provider/OAuth secrets and media presign URLs are stripped before anything is queued.
- Endpoints are workspace-scoped: possession of an endpoint UUID from another workspace does nothing.
- Delivery is at-least-once per accepted event occurrence; deduplicate on
x-publisher-event-id.
Developer tools availability
The Developers page lists workspace API keys and webhook endpoints independently of signing-secret encryption configuration. Creating a webhook requires valid server encryption configuration; ask the deployment operator to resolve a configuration warning. API-key management remains available. Existing signing secrets are never shown again.