Webhook / REST

The webhook integration is the most flexible option: when an article is ready, RankPine sends it as a JSON payload via HTTP POST to an endpoint you control. Use it to push articles into a custom CMS, trigger a static-site rebuild, drop files in a repo, or anything else you can script.

What you'll need

• A public HTTPS endpoint that accepts POST requests and responds with a 2xx status
• A server-side signing secret. It is optional for the generic transport but required by the production receiver template below.
• Persistent article storage and a public article route in your application.

Start with the shared receiver

Download or copy the dependency-free RankPine webhook receiver template. It uses the Web Request/Response APIs supported by Node, Deno, Edge Functions, and modern full-stack frameworks. You provide a small persistence adapter.

The reference implementation:

• verifies X-RankPine-Signature against the exact raw body before parsing;
• rejects invalid, stale, and future-dated requests outside a five-minute window;
• validates both verification and publish payloads;
• calls upsertByRankPineId with article.id as the idempotency key;
• preserves HTML, Markdown, metadata, featured and inline images, and scheduledFor;
• returns the stable external ID and canonical URL from your adapter; and
• calls refreshSitemap before acknowledging a delivery.

Connect in RankPine

Go to Integrations, click Connect on Webhook, and fill in the dialog:

When you connect, RankPine sends a verification ping to your endpoint. It must respond 2xx or the connection won't save.

Verification ping

{
  "event": "verification",
  "sentAt": "2026-06-29T09:00:00.000Z"
}

Respond with any 2xx status to confirm the endpoint is reachable.

The publish payload

When an article publishes, RankPine sends a POST with this body:

{
  "event": "article.published",
  "publishedAt": "2026-06-29T09:00:00.000Z",
  "site": {
    "name": "Acme",
    "url": "https://acme.com",
    "language": "en"
  },
  "article": {
    "id": "1e2b3c4d-…",
    "title": "How to choose a CRM",
    "slug": "how-to-choose-a-crm",
    "metaDescription": "A practical guide to picking the right CRM…",
    "scheduledFor": "2026-06-29T09:00:00.000Z",
    "language": "en",
    "translationGroupId": null,
    "wordCount": 1840,
    "seoScore": 86,
    "sources": [{ "url": "https://example.com/study", "title": "Industry study" }],
    "markdown": "# How to choose a CRM\n\n…",
    "html": "<h1>How to choose a CRM</h1>…"
  },
  "featuredImage": {
    "url": "https://cdn.rankpine.com/…/hero.png",
    "alt": "How to choose a CRM"
  },
  "images": [{ "url": "https://cdn.rankpine.com/…/diagram.png", "alt": "CRM dashboard" }]
}

Notes:

• article.markdown is included only if Include Markdown is on; article.html only if Include HTML is on.
• article.id is RankPine's stable article identifier. article.scheduledFor is the original calendar time, or null for an unscheduled article. Use article.id for idempotency; a schedule can change and is not an identity.
• featuredImage is the purpose-built 1200×630 cover/OG image, or null. images contains inline body images in document order. Both use RankPine's CDN.
• Inline images inside html/markdown already point at those same CDN URLs.
• article.language is the language this article is written in. site.language is your site's main language — on a multi-language site they differ.
• article.translationGroupId is null unless the article has translations. See below.

Multi-language sites

If you've set additional languages, each version of an article is published separately — one POST per language, each with its own slug, its own language, and its own id/url in your response. There is no single request containing all of them.

Every version of the same article shares one translationGroupId, so you can tell which posts belong together and wire up hreflang yourself:

// three separate POSTs
{ "article": { "slug": "how-to-choose-a-crm",    "language": "en", "translationGroupId": "a1b2c3…" } }
{ "article": { "slug": "crm-auswahl",            "language": "de", "translationGroupId": "a1b2c3…" } }
{ "article": { "slug": "como-elegir-un-crm",     "language": "es", "translationGroupId": "a1b2c3…" } }

The group id is the original article's own id, so the original arrives with translationGroupId equal to its own identity, and every translation carries the same value. A site with no additional languages always sends null.

Request headers

Your response

Respond 2xx to acknowledge. Optionally return JSON to tell RankPine where the article landed:

{ "id": "post_123", "url": "https://acme.com/blog/how-to-choose-a-crm" }

If you return an id and url, RankPine records them against the article. Keep both stable for the same article.id; this lets subsequent edits update the same external post. If you don't return them, a 2xx still acknowledges delivery, but RankPine can only record a generic fallback identity.

Verifying the signature

If you set a signing secret, every request includes an X-RankPine-Signature header. It's an HMAC-SHA256 of the raw request body, hex-encoded, prefixed with sha256=. Recompute it with your secret and compare — reject the request if it doesn't match.

The shared receiver uses Web Crypto's HMAC verification, which avoids a normal string comparison and works across Node and Edge runtimes. If you implement your own Node receiver, compare equal-length signature bytes with crypto.timingSafeEqual.

Guided website-builder setup

Each guide below installs this same receiver contract in the builder's supported server runtime. All six still connect to Webhook / REST in RankPine.

Troubleshooting