Connect Webhook to AltoRank

Webhook authenticates with a your endpoint, optionally signed that you create and can revoke yourself. Connecting it makes Webhook an available destination — it does not give AltoRank permission to publish. That still takes a person approving the draft.

What you will need

Setup

1. 1 Create the credential in Webhook

   Go to Wherever you run it. AltoRank never asks for your Webhook login: you create a scoped credential there and paste it here, so revoking our access later is one click on your side and does not change how you sign in.

2. 2 Add the connection in AltoRank

   In your workspace, open Integrations, choose Webhook, and fill in webhook url. The connection is tested before it saves, so a wrong value fails here rather than silently at publish time.

3. 3 Approve an article

   Nothing publishes on connection. Open a draft, read the fact-check verdict, and approve it. Only then does AltoRank call Webhook. You can also turn on automatic publishing for the workspace, which ships after a hold you can veto; either way there is no agent route around the approval.

What approving does in Webhook

The requests your endpoint receives

Three actions, one endpoint, always POST with a JSON body. The article ships as rendered HTML with its slug and approved meta description; there is no separate Markdown field. tags is included only when the article carries tags.

POST <your endpoint>
Content-Type: application/json
X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>   (only when a signing secret is set)
<your extra headers, if configured>

{
  "action": "publish",
  "article": {
    "title": "The article title",
    "html": "<h2>...</h2><p>...</p>",
    "slug": "the-article-slug",
    "metaDescription": "The approved meta description",
    "publishedAt": "2026-09-05T08:00:00.000Z"
  }
}

{ "action": "unpublish", "externalId": "<the id your endpoint returned on publish>" }

{ "action": "test" }

What to return

Any 2xx status counts as published. A JSON body is optional; when present, id (or externalId) is stored and sent back to you on unpublish, and url (or link) is recorded as where the article lives. Return 2xx only once you have stored the article: there is no automatic retry, and a non-2xx marks the publish as failed in the log so an editor can retry it from the article.

HTTP 200
Content-Type: application/json

{ "id": "your-record-id", "url": "https://example.com/blog/the-article-slug" }

Verifying the signature

With a signing secret set, every request carries X-Webhook-Signature: the string sha256= followed by the hex HMAC-SHA256 of the raw request body. Compute it over the bytes you received, before parsing, and compare in constant time.

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

const expected = 'sha256=' + createHmac('sha256', process.env.SIGNING_SECRET).update(rawBody).digest('hex');
const given = req.headers['x-webhook-signature'] ?? '';
const ok = given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));

Worth knowing

• The escape hatch: if your stack is not in the list, this is how you publish to it.
• Nothing about the approval gate changes. The webhook fires when the draft is approved, by a person or by the rule they set, not when it is generated.
• Delivery is one attempt. A non-2xx response marks the publish as failed in the publish log and it can be retried from the article; there is no automatic retry, so return 2xx only once you have stored the article.

The adapter behind this page is apps/web/lib/cms/webhook.ts . If this page and that file disagree, the file is right and the page has a bug.