Custom webhooks for any CMS

In shortA custom webhook lets AI Rank Lab publish to any CMS or app you control. Create it from an article's publish panel with Add Webhook and choose Standard (v1): AI Rank Lab then sends one signed JSON request per article, with a signing secret shown once. Your endpoint verifies the HMAC signature, stores the idempotency key, and returns 2xx with the live URL. Timeouts, 429 and 5xx errors are retried after 1, 5 and 15 minutes; other 4xx responses are final.

When to use a custom webhook

Use it when your site is not WordPress, or when you want full control over how articles land: a headless CMS, a static-site build, a Next.js blog, or a script that drops articles into a review queue. You need a developer who can build a small HTTPS endpoint. For WordPress, use Connect WordPress instead.

Two payload modes

Create a Standard (v1) webhook

1. Open the publish panelOpen any article in Content → Write → AI content writer and click Publish to CMS. Below Publish Content, the Webhooks card lists your endpoints. Click Add Webhook.
2. Fill in the endpointEnter a Name, the Endpoint URL (the final https address: publishing does not follow redirects), the Method, and any Headers your endpoint needs. Set Payload mode to Standard (v1) — recommended.
3. Copy the signing secretWhen you save, the Copy your signing secret dialog shows a secret starting whsec_. Copy it into your receiver now and click I've saved it. It is shown once and cannot be retrieved. The dialog says you can make a new one by editing the webhook, but the edit form has no secret field today, so if you lose it, delete the webhook and add it again.

What your endpoint must do

Each publish is one request, using the method you chose (normally POST), with these headers: X-AIRankLab-Event: article.publish, X-AIRankLab-Timestamp, X-AIRankLab-Signature and X-Idempotency-Key, plus any custom headers you set.

1. Verify the signature on the raw body, before parsing. Compute HMAC-SHA256 of timestamp + "." + rawBody with your secret, hex-encode it, prefix sha256=, and compare with X-AIRankLab-Signature. Parsing and re-encoding the JSON first changes the bytes and the signature will never match.
2. Reject old requests. Refuse a timestamp more than 5 minutes old, so a captured request can't be replayed.
3. Treat the idempotency key as already handled. The key stays the same while the article is unchanged. If you have seen it, return the existing post instead of creating another.
4. Update, don't duplicate. When the same article is published again after edits, the key changes; match on the article's id and update the post.
5. Return 2xx with the live URL, for example { "ok": true, "postId": "1234", "link": "https://..." }. AI Rank Lab reads the URL back and uses it for citation tracking.
6. Ignore fields you don't recognise. New fields can be added within version 1; a receiver that rejects unknown keys will break.

Status codes and retries

Legacy template mode in one paragraph

A template webhook sends whatever JSON you write in Payload Template (JSON), with placeholders such as {{articleTitle}}, {{content}}, {{metaDescription}} and {{slug}} filled in. Click any entry under Available Placeholders (Click to copy) to copy it. Write "***" as the value of apiKey and the stored key is inserted at send time. Keep it for receivers that already expect a fixed format; prefer Standard (v1) for anything new.