Publish connector
Publish to any site with a signed webhook
RankEcho's webhook sends each finished piece to an HTTPS address you choose, as JSON with the title, meta description, slug, HTML, Markdown and JSON-LD, signed with HMAC-SHA256 so your server can check it came from RankEcho. It works with any CMS or site that can run a short script, and nothing is sent until someone presses Send.
Set it up
- In RankEcho, open your site and choose Publish to your site.
- Add your endpoint's HTTPS address. Use a host name on the standard port; RankEcho does not send to IP addresses or follow redirects.
- Show the signing secret and store it on your server, for example as RANKECHO_WEBHOOK_SECRET.
- Press Send a test. Your endpoint gets a ping event; answer with any 2xx.
- On a finished piece, choose Draft or Live and press Send.
On WordPress: the RankEcho Connector plugin
No script to write. Download the plugin (.zip), upload it under Plugins, Add New, Upload, and activate it. Settings, RankEcho shows the address to add in RankEcho; paste the signing secret back there and press Send a test.
- Drafts arrive as drafts. A draft of a change to a live page is saved beside it and never touches the live page.
- A live change updates the page in place and keeps its previous title, body and SEO fields, so the change can be undone.
- If the page was edited in WordPress since RankEcho last wrote it, or someone is editing it now, nothing is overwritten: RankEcho's version waits as a draft beside it.
- Sets the Yoast SEO or Rank Math title and meta description, adds the JSON-LD, and answers with the page's address so RankEcho starts the test on its own.
What arrives
| Header | What it holds |
|---|---|
RankEcho-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your signing secret> |
RankEcho-Event | piece.published, piece.reverted (undo a live change), or ping for a test |
RankEcho-Delivery | The delivery id, the same on every retry |
Content-Type | application/json |
User-Agent | RankEcho-Webhooks/1.0 (+https://rankecho.io/connect/webhook) |
The body is JSON, version 2026-11-16:
{
"version": "2026-11-16",
"id": "dlv_2b7c91e0d4",
"event": "piece.published",
"created_at": "2026-11-16T15:00:00.000Z",
"site": {
"id": "site_123",
"domain": "example.com"
},
"piece": {
"id": "pc_8f2k",
"kind": "new",
"status": "draft",
"title": "How to check index coverage in Search Console",
"description": "Find which pages Google indexed, which it left out and why, in five minutes.",
"slug": "how-to-check-index-coverage-in-search-console",
"url": null,
"search": "how to check index coverage",
"html": "<h1>How to check index coverage in Search Console</h1>\n<p>Open the Pages report...</p>",
"markdown": "# How to check index coverage in Search Console\n\nOpen the Pages report...",
"front_matter_markdown": "---\ntitle: \"How to check index coverage in Search Console\"\ndescription: \"Find which pages Google indexed, which it left out and why, in five minutes.\"\n---\n\n# How to check index coverage...",
"json_ld": [
{
"@type": "Article",
"headline": "How to check index coverage in Search Console"
}
],
"json_ld_script": "<script type=\"application/ld+json\">...</script>",
"note": null
}
}| Field | Meaning |
|---|---|
id | The piece's id in RankEcho. The same each time this piece is sent. |
kind | new for a new page; refresh for an existing page, with its url. |
status | draft or live, as the person who pressed Send chose. |
title, description, slug | The page title, the meta description and a URL slug. |
html | The article as HTML. For a refresh, the whole page with the changed sections and head tags spliced in. |
markdown, front_matter_markdown | The article as Markdown, with and without YAML front matter. |
json_ld, json_ld_script | The structured data as a JSON-LD graph, and as a ready script tag. |
search | The search or question the piece answers. |
Check the signature
Compute HMAC-SHA256 of the timestamp, a dot and the raw body with your secret, compare it with v1 in constant time, and refuse old timestamps. In Node.js:
import crypto from "node:crypto";
// rawBody: the request body exactly as received (a string, not parsed JSON).
export function verifyRankEcho(rawBody, header, secret) {
const parts = Object.fromEntries((header || "").split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const given = String(parts.v1 || "");
return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
In PHP, for example in a WordPress plugin or a small endpoint:
<?php
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_RANKECHO_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('RANKECHO_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int)($sig['t'] ?? 0)) > 300) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
// $event['piece']['id'] stays the same each time a piece is sent: update the post you made for it.
$url = 'https://example.com/blog/' . $event['piece']['slug']; // the address of the post you made
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['url' => $url]); // lets RankEcho check it is live and start a testAnswers and retries
For a live piece, answer with the page's address as JSON, {"url": "https://yoursite.com/blog/the-slug"} (link or permalink work too). RankEcho then checks the page is live and starts a before-and-after test on it automatically, with a marker on your Search charts. The address must be on your site.
Answer 2xx within 10 seconds once you have stored the piece; do slow work afterwards. With no answer, or 408, 429 or 5xx, RankEcho tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. Every attempt and its answer shows under Publish to your site.
Other connectors
| Connector | State | What it does |
|---|---|---|
| Signed webhook | Live | Any site or CMS that can take an HTTPS request: the piece as HTML, Markdown and JSON-LD, signed with HMAC-SHA256. |
| WordPress | Live | The RankEcho Connector plugin on the signed webhook: drafts or live posts, pages updated in place with the previous version kept to undo, Yoast and Rank Math titles set. |
| Webflow | Planned | CMS collection items, updated in place. |
| Shopify | Planned | Blog articles, updated in place. |
| Ghost | Planned | Posts as drafts or live, updated in place. |
| Wix | Planned | Blog posts as drafts or live. |
Native connectors follow in this order. Until yours is live, the webhook or the export on each piece covers it. Looking for the AI assistant connector instead? See Connect Search Console to your AI assistant.
Questions
Does RankEcho publish on its own?
No. Auto-publish is off. A piece is sent only when someone in your workspace presses Send on it, as a draft or live, and your endpoint decides what to do with it.
How do I update a page I already published?
Send the piece again. piece.id stays the same for the same piece, so store it with your post and update that post when the id comes back. A refresh of an existing page also carries its url.
What if my endpoint is down?
RankEcho tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours when there is no answer within 10 seconds, or the answer is 408, 429 or 5xx. Any other non-2xx answer counts as a refusal and is not retried.
Can the same delivery arrive twice?
Rarely, yes, as with any webhook. The RankEcho-Delivery header and the id field are the same on every attempt, so skip an id you have already handled.
Where do I find the signing secret?
In RankEcho, open your site, then Publish to your site, and show the signing secret. Only the workspace owner sees it. Make a new one there if it ever leaks; the old one stops verifying at once.
How does RankEcho measure a published piece?
When a piece is sent live and your endpoint answers with the page's address, as {"url": "https://..."}, RankEcho marks the change shipped, reads the page until the new text is on it, and then measures the page against the numbers from before the change. The change shows on your Search charts and the result lands in Results and the weekly digest. Without an address, press Mark shipped on the piece.
Can RankEcho undo a change it published?
Yes, when your endpoint keeps the version it replaced. Revert, Undo on your site sends piece.reverted with the same piece.id and url. Put the old version back and answer {"reverted": true}; only then does RankEcho stop the Test and put the change back in the plan. Refuse with a 409 and an error message when the page changed since, so that edit is not lost. The WordPress plugin does all of this.
Does RankEcho follow redirects?
No. Give the final HTTPS address. A 3xx answer is recorded as a refusal so a payload never lands somewhere you did not choose.
