REST API

Webhooks

Get a signed HTTPS request the moment something happens in PostNinja: a post goes out or fails, a teammate submits a post for approval, an account needs reconnecting, a comment arrives. Ideal for n8n, Zapier, Make, Slack alerts or your own backend.

View as Markdown

Set up an endpoint

Add the URL under Settings → API → Webhooks, or with POST /api/v1/webhooks. It must be a public https:// address. Up to 10 per workspace.
Pick the events you want, or leave it empty for all of them.
Copy the signing secret (whsec_…). It's shown once; you can rotate it in Settings.
Click Send test event: PostNinja sends one webhook.test so you can check your receiver and its signature check.

Events

Event	When	In `data`
`post.created`	Posts: Created (draft or waiting)	`post`; `status` (`draft` or `awaiting_approval`)
`post.scheduled`	Posts: Scheduled	`post`; `status`
`post.updated`	Posts: Changed	`post`; `status`
`post.rescheduled`	Posts: Moved to a new time	`post`
`post.deleted`	Posts: Deleted	`postId` only (the post is gone)
`post.retried`	Posts: Retried	`post`
`post.published`	Posts: Published	`post` (every target published, with links)
`post.partial`	Posts: Partly published	`post` (see each target's `status` and `error`)
`post.failed`	Posts: Failed	`post` (see each target's `error`)
`post.submitted`	Approvals: Submitted for approval	`post`
`post.approved`	Approvals: Approved	`post`; `note` if one was left; `profileId` when approved from a client review link
`post.changes_requested`	Approvals: Changes requested	`post`; `note`; `profileId` when sent back from a client review link
`account.connected`	Accounts: Connected	`accountId`, `platform`, `username`
`account.disconnected`	Accounts: Disconnected	`accountId`, `platform`
`account.needs_reconnect`	Accounts: Needs reconnecting	`accountId`, `platform`, `username`, `note` (why)
`member.joined`	Team: Member joined	`role`
`comment.received`	Comments: New comment	`accountId`, `platform`, `inboxItemId`, `author`, `text` (first 280 characters), `reply`, `permalink`, and `post` when it's on a post from PostNinja
`message.received`	Direct messages: New message	`accountId`, `platform`, `conversationId`, `messageId`, `from` (username or name), `text` (first 280 characters), `attachments` (how many)
`message.sent`	Direct messages: Reply sent from PostNinja	`accountId`, `platform`, `conversationId`, `messageId`, `to`, `text` (first 280 characters); sent from PostNinja by a person or through the API

Post events carry the post exactly as GET /api/v1/posts/:id returns it, in data.post. When many comments or messages arrive at once, comment.received and message.received send one summary instead (count, platforms, summary: true).

The request

Header	Value
`Content-Type`	`application/json`
`PostNinja-Event`	The event name, e.g. `post.published`.
`PostNinja-Delivery`	This attempt's id. A redelivery gets a new one; the body's `id` stays the same.
`PostNinja-Signature`	`t=<unix seconds>,v1=<hex HMAC-SHA256>`

Body

{
  "id": "c2a1b3d4-e5f6-4a7b-9c8d-e9f0a1b2c3d4",
  "event": "post.published",
  "createdAt": "2026-10-12T09:00:06.512Z",
  "data": {
    "postId": "0d3c4b5a-6978-4e1f-a2b3-c4d5e6f7a8b9",
    "post": {
      "id": "0d3c4b5a-6978-4e1f-a2b3-c4d5e6f7a8b9",
      "status": "published",
      "content": "We just shipped dark mode. Here's the full story.",
      "platformContent": {
        "x": "Dark mode is here 🌙"
      },
      "xThread": [],
      "xThreadMedia": [],
      "instagramFormat": "post",
      "tiktok": {},
      "firstComment": null,
      "youtubeTitle": null,
      "youtubeThumbnail": null,
      "queued": false,
      "scheduledAt": "2026-10-12T09:00:00.000Z",
      "publishedAt": "2026-10-12T09:00:06.000Z",
      "createdAt": "2026-10-06T14:21:07.512Z",
      "media": [
        {
          "id": "5b9d1c2e-3f4a-4b5c-9d6e-7f8a9b0c1d2e",
          "kind": "image",
          "url": "https://postninja.app/media/5b9d1c2e-3f4a-4b5c-9d6e-7f8a9b0c1d2e.jpg",
          "previewUrl": null
        }
      ],
      "targets": [
        {
          "accountId": "3f2c8a10-6d1e-4b7a-9c55-1e2f3a4b5c6d",
          "platform": "x",
          "username": "acme",
          "status": "published",
          "url": "https://x.com/acme/status/1843210987654321098",
          "error": null
        },
        {
          "accountId": "8b7e1d22-0c4f-4e8a-a1b2-9d8c7b6a5f40",
          "platform": "instagram",
          "username": "acme.studio",
          "status": "failed",
          "url": null,
          "error": "Instagram: photos must be between 4:5 (portrait) and 1.91:1 (landscape). Crop this one first."
        }
      ]
    }
  }
}

Verify the signature

v1 is the HMAC-SHA256 of {t}.{raw body} with your endpoint's secret, in hex. Compute it over the raw body exactly as received (before parsing JSON), compare in constant time, and reject requests whose t is more than 5 minutes old.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.POSTNINJA_WEBHOOK_SECRET; // whsec_…

app.post("/webhooks/postninja", express.raw({ type: "application/json" }), (req, res) => {
  const parts = Object.fromEntries((req.get("PostNinja-Signature") ?? "").split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", SECRET).update(`${parts.t}.${req.body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const valid =
    fresh &&
    typeof parts.v1 === "string" &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!valid) return res.status(400).send("Bad signature");

  const event = JSON.parse(req.body.toString("utf8"));
  // Skip events you've already handled: deliveries can repeat.
  console.log(event.id, event.event, event.data.postId);
  res.sendStatus(204);
});

Python (Flask)

import hashlib, hmac, json, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["POSTNINJA_WEBHOOK_SECRET"].encode()  # whsec_…

@app.post("/webhooks/postninja")
def postninja():
    raw = request.get_data()  # the raw body, before parsing
    parts = dict(p.split("=", 1) for p in request.headers.get("PostNinja-Signature", "").split(",") if "=" in p)
    t, v1 = parts.get("t", "0"), parts.get("v1", "")
    expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, expected):
        abort(400)
    event = json.loads(raw)
    print(event["id"], event["event"], event["data"].get("postId"))
    return "", 204

Retries and switching off

Answer with any 2xx status within 10 seconds. Do slow work after answering.
Anything else is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h; after that the delivery is marked failed.
After 50 failed attempts in a row, the endpoint is switched off and the workspace owner gets an email. Switch it back on in Settings; that resets the count.
Deliveries can arrive more than once or out of order. Use the body's id to skip events you've handled, and createdAt to order them.
Settings shows each endpoint's recent deliveries (status code and the start of your answer) and can Redeliver any of them. History is kept 30 days.

No-code tools

In n8n, Zapier or Make, create a webhook trigger, paste its URL as the endpoint, and choose the events. To verify signatures there, compute the HMAC in a code step with the raw body; if your tool only gives you parsed JSON, keep the URL secret instead and check the event by fetching the post with the REST API.

Webhooks

Set up an endpoint#

Events#

The request#

Verify the signature#