Postrex
Start free

Connect a custom site with the publish webhook

The publish webhook sends every post Postrex publishes for you to a URL on your own site, as a signed JSON request with the full article — HTML, Markdown, meta description and featured image. You save the URL in Settings, check the signature in a small handler and answer with the post’s address. If your endpoint does not answer, Postrex retries for about 15 minutes and tells you when a delivery fails.

Set it up

  1. In the dashboard, open Settings → Developers & integrations → Publish webhook, enter the URL of your endpoint and save. It must be an http:// or https:// address that is reachable from the internet; private and internal addresses are refused.
  2. Copy the signing secret that is shown and keep it in an environment variable, for example POSTREX_WEBHOOK_SECRET. It is shown once. Saving the URL again creates a new secret.
  3. Add a receiver to your site — complete examples are below. It checks the signature, stores the post and answers with a 2xx status within 10 seconds.
  4. Click Send test event. The result appears at once: the HTTP status your endpoint answered with, how long it took, or the error.
  5. Publish a post. Settings lists the last 10 deliveries with their status, the number of attempts and your endpoint’s answer.

Events

EventWhen it is sent
post.publishedA post was published for the first time.
post.updatedA post that was already published was published again — its content may have changed.
post.deletedA published post was deleted in Postrex.
testYou clicked “Send test event” in Settings. Carries a sample post — do not store it.
  • A post is published when you click Publish, when its scheduled time comes, or when your schedule publishes automatically. Each of these sends the event — also when the site has a CMS connection.
  • post.published and post.updated both carry the whole post. Treat both as “store this post under post.id”: if you add the webhook after a post was first published, the first event you get for it is post.updated.
  • post.deleted is sent when you delete a post in the dashboard that had been published. Postrex removes nothing from your site itself.

The request

Every event is a POST to your URL with a JSON body and these headers:

HeaderValue
content-typeapplication/json
acceptapplication/json
user-agentPostrexBot/1.0 (+https://postrex.com/bot)
x-postrex-signaturet=<unix seconds>,v1=<hex signature> — see “Verify the signature”.
x-postrex-eventThe event name: post.published, post.updated, post.deleted, test.
x-postrex-deliveryThe delivery’s id (a UUID). The same on every attempt of one delivery.

Payload

The body is { event, post }. This is a post.published event with the sample post a test event carries (the body is sent on one line; it is laid out here for reading):

{
  "event": "post.published",
  "post": {
    "id": "3f6c1e2a-9b7d-4c58-8a41-5d2e7f90b1c3",
    "title": "How to Choose a Standing Desk",
    "slug": "how-to-choose-a-standing-desk",
    "metaDescription": "What to look for in a standing desk: height range, stability, motor and desktop size — with a short checklist.",
    "bodyMarkdown": "## What matters most\n\nHeight range and stability come first. A desk that wobbles at standing height will not be used.\n\n## Checklist\n\n- Height range fits you sitting and standing\n- Stable at full height\n- Desktop deep enough for your screen",
    "bodyHtml": "<h2>What matters most</h2>\n<p>Height range and stability come first. A desk that wobbles at standing height will not be used.</p>\n<h2>Checklist</h2>\n<ul>\n<li>Height range fits you sitting and standing</li>\n<li>Stable at full height</li>\n<li>Desktop deep enough for your screen</li>\n</ul>",
    "featuredImageUrl": "https://postrex.com/api/images/7d0c9a52-1e4b-4f6a-b3c8-2a9e5d1f7b60",
    "altText": "A standing desk at standing height in a home office",
    "language": "en",
    "publishedAt": "2026-11-17T09:30:00.000Z",
    "url": null
  }
}
FieldWhat it is
post.idThe post's id in Postrex (a UUID). It never changes — store your copy under it.
post.titleThe headline.
post.slugThe URL slug Postrex suggests for the post.
post.metaDescriptionThe meta description, for your page's <meta name="description">.
post.bodyMarkdownThe full article as Markdown: byline, table of contents, body, FAQ and related posts.
post.bodyHtmlThe same article rendered to HTML, ready to put into your page.
post.featuredImageUrlURL of the featured image, or null.
post.altTextAlt text for the featured image, or null.
post.languageLanguage code of the article, e.g. "en".
post.publishedAtWhen this publish happened (ISO 8601, UTC) — on post.updated, the time of the update.
post.urlThe post's public address as Postrex knows it — from a connected CMS, or the one your endpoint reported earlier — otherwise null.

post.updated and test have the same fields. A post.deleted event names the post with post.id, post.slug, post.url only:

{
  "event": "post.deleted",
  "post": {
    "id": "3f6c1e2a-9b7d-4c58-8a41-5d2e7f90b1c3",
    "slug": "how-to-choose-a-standing-desk",
    "url": "https://example.com/blog/how-to-choose-a-standing-desk"
  }
}

Verify the signature

The x-postrex-signature header has the form t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256, keyed with your signing secret, of the timestamp, a dot and the raw request body: <t>.<raw body>. To verify a request:

  1. Read the body as raw text. Parsing the JSON and serialising it again changes the bytes, and the signature no longer matches.
  2. Compute the HMAC-SHA256 of <t>.<raw body> with your secret and compare it with v1 in constant time.
  3. Refuse a request whose t is more than 5 minutes from your server’s clock. The timestamp is part of what is signed, so a recorded request cannot be replayed later.

Each receiver below does this, stores the post, handles a retried delivery once and answers with the post’s address. Replace the in-memory store with your database and example.com with your own domain.

Next.js route handler

// app/api/postrex-webhook/route.ts
import crypto from "node:crypto";

// Replace these two with your database.
const posts = new Map<string, { title: string; slug: string; html: string }>();
const handled = new Map<string, object>(); // delivery id -> the answer we gave

function verifyPostrexSignature(secret: string, rawBody: string, header: string | null, toleranceSeconds = 300): boolean {
  // The header is "t=<unix seconds>,v1=<hex signature>".
  const t = /(?:^|,)\s*t=(\d+)/.exec(header ?? "")?.[1];
  const v1 = /(?:^|,)\s*v1=([0-9a-f]{64})/.exec(header ?? "")?.[1];
  if (!t || !v1) return false;
  // An old timestamp is a replayed request.
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  // The signature covers the timestamp and the raw body, exactly as received.
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

export async function POST(req: Request) {
  // Read the body as text: the signature is over these exact bytes.
  const rawBody = await req.text();
  const secret = process.env.POSTREX_WEBHOOK_SECRET!;
  if (!verifyPostrexSignature(secret, rawBody, req.headers.get("x-postrex-signature"))) {
    return new Response("Invalid signature", { status: 401 });
  }

  // A retry carries the same delivery id: answer as before, do nothing twice.
  const deliveryId = req.headers.get("x-postrex-delivery") ?? "";
  const before = handled.get(deliveryId);
  if (before) return Response.json(before);

  const { event, post } = JSON.parse(rawBody);
  let answer: object = { ok: true };
  if (event === "post.published" || event === "post.updated") {
    // Both carry the whole post: store it under post.id.
    posts.set(post.id, { title: post.title, slug: post.slug, html: post.bodyHtml });
    // Tell Postrex where the post lives on your site.
    answer = { url: `https://example.com/blog/${post.slug}` };
  } else if (event === "post.deleted") {
    posts.delete(post.id);
  }
  // A "test" event needs nothing but the 200.
  handled.set(deliveryId, answer);
  return Response.json(answer);
}

Express

// server.js
import crypto from "node:crypto";
import express from "express";

const app = express();
// Replace these two with your database.
const posts = new Map();
const handled = new Map(); // delivery id -> the answer we gave

function verifyPostrexSignature(secret, rawBody, header, toleranceSeconds = 300) {
  // The header is "t=<unix seconds>,v1=<hex signature>".
  const t = /(?:^|,)\s*t=(\d+)/.exec(header ?? "")?.[1];
  const v1 = /(?:^|,)\s*v1=([0-9a-f]{64})/.exec(header ?? "")?.[1];
  if (!t || !v1) return false;
  // An old timestamp is a replayed request.
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  // The signature covers the timestamp and the raw body, exactly as received.
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

// express.raw keeps the body as the bytes that were signed.
app.post("/postrex-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const secret = process.env.POSTREX_WEBHOOK_SECRET;
  if (!verifyPostrexSignature(secret, rawBody, req.get("x-postrex-signature"))) {
    return res.status(401).send("Invalid signature");
  }

  // A retry carries the same delivery id: answer as before, do nothing twice.
  const deliveryId = req.get("x-postrex-delivery") ?? "";
  const before = handled.get(deliveryId);
  if (before) return res.json(before);

  const { event, post } = JSON.parse(rawBody);
  let answer = { ok: true };
  if (event === "post.published" || event === "post.updated") {
    // Both carry the whole post: store it under post.id.
    posts.set(post.id, { title: post.title, slug: post.slug, html: post.bodyHtml });
    // Tell Postrex where the post lives on your site.
    answer = { url: `https://example.com/blog/${post.slug}` };
  } else if (event === "post.deleted") {
    posts.delete(post.id);
  }
  // A "test" event needs nothing but the 200.
  handled.set(deliveryId, answer);
  res.json(answer);
});

app.listen(3000);

PHP

<?php
// postrex-webhook.php

function verify_postrex_signature(string $secret, string $rawBody, string $header, int $tolerance = 300): bool {
    // The header is "t=<unix seconds>,v1=<hex signature>".
    if (!preg_match('/(?:^|,)\s*t=(\d+)/', $header, $t) || !preg_match('/(?:^|,)\s*v1=([0-9a-f]{64})/', $header, $v1)) {
        return false;
    }
    // An old timestamp is a replayed request.
    if (abs(time() - (int) $t[1]) > $tolerance) {
        return false;
    }
    // The signature covers the timestamp and the raw body, exactly as received.
    $expected = hash_hmac('sha256', $t[1] . '.' . $rawBody, $secret);
    return hash_equals($expected, $v1[1]);
}

// Read the raw body: the signature is over these exact bytes.
$rawBody = file_get_contents('php://input');
$secret = getenv('POSTREX_WEBHOOK_SECRET');
if (!verify_postrex_signature($secret, $rawBody, $_SERVER['HTTP_X_POSTREX_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit('Invalid signature');
}

// Replace this folder with your database (files like these belong outside the web root).
$dir = __DIR__ . '/postrex-data';
@mkdir($dir . '/handled', 0700, true);
@mkdir($dir . '/posts', 0700, true);
header('Content-Type: application/json');

// A retry carries the same delivery id: answer as before, do nothing twice.
$deliveryId = preg_replace('/[^0-9a-f-]/', '', $_SERVER['HTTP_X_POSTREX_DELIVERY'] ?? '');
$handled = $dir . '/handled/' . $deliveryId . '.json';
if (is_file($handled)) {
    exit(file_get_contents($handled));
}

$payload = json_decode($rawBody, true);
$post = $payload['post'];
$file = $dir . '/posts/' . preg_replace('/[^0-9a-f-]/', '', $post['id']) . '.json';
$answer = ['ok' => true];
if ($payload['event'] === 'post.published' || $payload['event'] === 'post.updated') {
    // Both carry the whole post: store it under its id.
    file_put_contents($file, json_encode(['title' => $post['title'], 'slug' => $post['slug'], 'html' => $post['bodyHtml']]));
    // Tell Postrex where the post lives on your site.
    $answer = ['url' => 'https://example.com/blog/' . $post['slug']];
} elseif ($payload['event'] === 'post.deleted') {
    @unlink($file);
}
// A "test" event needs nothing but the 200.
file_put_contents($handled, json_encode($answer));
echo json_encode($answer);

Answer with the post’s address

Any 2xx status means “delivered”. A 2xx answer may also carry JSON that says where the post now lives on your site:

{ "url": "https://example.com/blog/how-to-choose-a-standing-desk" }
  • Postrex stores that address with the post. The dashboard then links to it (“View live”), later articles can link to the post under “Related posts”, the daily sitemap check looks for it, and Google Search Console numbers are matched to it.
  • The address is taken only when it is an http:// or https:// URL on your site’s own domain — the one you entered in Postrex — or a subdomain of it, and at most 500 characters long. Anything else is ignored; the delivery still counts as delivered.
  • Everything else in the answer is ignored, and only the first 16 KB of it are read.
  • If the post was published to a connected CMS, the address the CMS returned is kept.
  • Redirects are not followed: a 3xx answer is a failed attempt, like any other status outside 2xx.

Retries and failures

  • The first attempt is made the moment the post is published. If it fails, Postrex tries again 1 minute later, 4 minutes after that and 10 minutes after that: 4 attempts within about 15 minutes.
  • An attempt fails when the answer is not 2xx, when there is no answer within 10 seconds, when the connection fails, or when the URL leads to a private or internal address.
  • Every attempt sends the same body and the same x-postrex-delivery, with a new timestamp and signature.
  • After the last failed attempt the delivery is marked failed. The account owner gets an email with the endpoint and the last error — unless “Publish & generation failures” emails are switched off in Settings, and at most one per site per hour — and the post carries a note in the dashboard that your site did not accept it.
  • Once your endpoint works again, click Retry now next to the failed delivery in Settings. It is offered while no newer delivery exists for the same post.
  • A newer event for the same post replaces one that is still waiting for a retry, so an old version never arrives after a new one. Switching the webhook off cancels what is waiting.
  • Test events are sent once and never retried; you can send 5 per minute. Deliveries are kept for 30 days.

Handle each delivery once

A retry can reach you after an attempt you already handled — for example when your answer was lost on the way. The x-postrex-delivery header is your idempotency key: it is the same on every attempt of one delivery and different for every other delivery. Remember the ids you have handled and answer a repeated one with the same 2xx answer without doing the work again, as the receivers above do. Storing posts under post.id has the same effect for the content itself: an update replaces the post instead of adding a second copy.

Other ways to get posts onto your site

  • Content API. Your site fetches the posts instead of receiving them. GET https://postrex.com/api/v1/posts returns { posts: [...] } with up to 100 published posts, newest first; GET https://postrex.com/api/v1/posts/{slug} returns { post } for one. Send the API key from Settings → Developers & integrations as Authorization: Bearer …; it is not accepted in the URL. Each post has the fields of the webhook’s post except url, plus faq, dateModified, jsonLd, analyticsBeacon. The limit is 120 requests per minute.
  • RSS feed. https://postrex.com/api/feed/{your site id} is an RSS 2.0 feed of your published posts with the full article HTML in each item. It needs no key; the link is on the Blog posts page of the dashboard.
  • Export. Every post in the dashboard can be downloaded as a Markdown or an HTML file.

The RSS feed and the export need no code on your site. If your site runs on a CMS that Postrex publishes to directly, connect it in Settings instead — see WordPress and Shopify. To let an AI agent work with your account, see Connect an AI agent (MCP).