Webhooks

Webhooks push events to your HTTPS endpoint so you do not need to poll GET /v1/posts/:id. Every delivery is signed; verify the signature before trusting the body.

Quick Start

1. Create an endpoint and store the returned secret (shown once).
2. Subscribe to the event types you need.
3. Respond with 2xx within 10 seconds.
4. Verify Onepostly-Signature on every request.

import { Configuration, WebhooksApi } from "@onepostly/sdk";

const webhooksApi = new WebhooksApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await webhooksApi.createWebhook({
  createWebhookBody: {
    "name": "Post events",
    "url": "https://example.com/hooks/onepostly",
    "secret": "s7a9Kx2mQ8vB4nR6tY3wZ1pL5oN0uMf",
    "events": [
      "post.platform.published"
    ],
    "enabled": true
  },
});
console.log(response);

{
  "webhook": {
    "id": "dlv_1",
    "name": "Post events",
    "url": "https://example.com/hooks/onepostly",
    "enabled": true,
    "events": [
      "post.platform.published"
    ],
    "secret": "s7a9Kx2mQ8vB4nR6tY3wZ1pL5oN0uMf"
  }
}

secret is returned only on create. List and get responses never include it.

Manage Endpoints

Event Catalog

Event names are platform-agnostic. Which platform fired an event lives in data.platform.

Posts

Payloads and lifecycle details in Post Webhooks.

Comments

List/read comment calls do not emit webhooks. Payloads in Comment Webhooks.

Messages

Payloads in Inbox Webhooks.

Engagement

Payloads in Engagement Webhooks.

Accounts

Payloads in Account Webhooks.

System

Envelope

Every delivery body is this envelope:

{
  "id": "event_post_platform_published_DEST_ID",
  "type": "post.platform.published",
  "createdAt": "2026-07-15T12:00:01.000Z",
  "organizationId": "WORKSPACE_ID",
  "data": { }
}

The payload examples on each subpage show only that event's data.

Request Headers

Verify Signatures

The signature is HMAC-SHA256 over timestamp + "." + rawBody using your endpoint secret.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyOnepostlySignature({ secret, rawBody, header, toleranceSec = 300 }) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=").map((s) => s.trim())),
  );
  const timestamp = Number(parts.t);
  const v1 = parts.v1;
  if (!timestamp || !v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSec) {
    return false;
  }

  const signedPayload = timestamp + "." + rawBody;
  const expected = createHmac("sha256", secret)
    .update(signedPayload, "utf8")
    .digest("hex");

  const a = Buffer.from(v1, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Verify against the raw request body. Do not re-serialize JSON first.

Delivery And Retries

Publishing never fails because a webhook endpoint is down. Deliveries are best-effort with retries.

Inspect recent attempts:

curl "https://api.onepostly.com/v1/webhooks/WEBHOOK_ID/deliveries?limit=20" \
  -H "x-api-key: op_YOUR_KEY"

{
  "deliveries": [
    {
      "id": "DLV_ID",
      "endpointId": "WH_ID",
      "eventId": "evt_123",
      "eventType": "post.published",
      "status": "success",
      "attemptCount": 1,
      "responseStatus": 200,
      "lastError": null,
      "createdAt": "2026-08-25T10:00:00.000Z",
      "deliveredAt": "2026-08-25T10:00:00.001Z"
    }
  ]
}

Each row includes status (pending, success, failed), attemptCount, responseStatus, and lastError.

Test Endpoint

Send a webhook.test event to one endpoint (regardless of its subscription):

curl -X POST https://api.onepostly.com/v1/webhooks/WEBHOOK_ID/test \
  -H "x-api-key: op_YOUR_KEY"

{
  "ok": true
}

Best Practices

• Prefer webhooks over polling for publish status
• Always verify signatures; reject unsigned or stale requests
• Treat envelope id as an idempotency key
• Keep handlers fast. Queue work and return 200 quickly
• Subscribe to account.expired and account.revoked so you can prompt users to reconnect

See also Quickstart, Post Webhooks, Comment Webhooks, Inbox Webhooks, Engagement Webhooks, and Account Webhooks.