API Reference

Webhooks

Receive post and billing events

Webhooks push OpenPost events to an HTTP endpoint you control. Every payload is signed with an HMAC so you can verify the request came from us.

Webhook endpoint management today is via the dashboard and a session-authenticated API (/api/webhooks). Per-event delivery is in active rollout — the event list below reflects the planned set as integration providers light up.

Setting up an endpoint

1

Deploy your receiver

Any public HTTPS endpoint that accepts POST requests. Respond 2xxquickly — if you need to do slow work, enqueue it and respond immediately.

2

Register the URL

Settings → Webhooks → Add endpoint. Pick which events to subscribe to. We generate a signing secret and show it once.

3

Copy the signing secret

Store the secret securely. You’ll use it to verify every incoming request.

Payload shape

json
{
  "event": "post.published",
  "data": {
    "post_id": "3a6f1e9e-4c2b-4a1d-9e3a-112233445566",
    "platform": "twitter",
    "platform_post_url": "https://x.com/user/status/1812345678901234567"
  },
  "timestamp": "2026-04-16T09:45:12Z"
}

Events (planned)

FieldTypeDescription
post.publishedpost publishes successfullyData: post_id, platform, platform_post_url.
post.failedpublish failedData: post_id, platform, error.
integration.connectednew account linkedData: integration_id, platform.
integration.disconnectedaccount lost authData: integration_id, reason.

Verifying signatures

Every request includes an X-OpenPost-Signatureheader containing an HMAC-SHA256 of the raw request body using your endpoint’s signing secret, encoded as lowercase hex.

http
X-OpenPost-Signature: 5257a8690a1c...
ts
import crypto from "crypto";
 
export function verifyOpenPost(rawBody: string, signatureHeader: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
 
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signatureHeader, "hex"),
  );
}
Use the rawrequest body string for the HMAC — not a JSON-parsed and re-stringified version. Any whitespace or key-order change will produce a different signature.

Endpoints

GET/api/webhooks

List webhook endpoints for the workspace (session-auth only today).

POST/api/webhooks

Create a webhook endpoint. Returns the signing secret once.

DELETE/api/webhooks

Remove an endpoint by id in the JSON body.

PreviousNotificationsNext All guides
Last updated April 2026 Edit this page