Stop polling. We push to you.
Subscribe an HTTPS endpoint and Rank Prompt POSTs the moment a report or scheduled run finishes across ChatGPT, Perplexity, Google AI Mode, Claude, Gemini, Muse, and Grok.
- HMAC-signed payloads
- Automatic retries
- No polling
POST /webhooks/rankprompt HTTP/1.1
Host: api.yourbrand.com
X-RP-Event: report.completed
X-RP-Event-Id: evt_9b2c7e1f…
X-RP-Signature: t=1751198400,v1=5f1e9c8a2b…
Content-Type: application/json
{
"id": "evt_9b2c7e1f…",
"type": "report.completed",
"api_version": "v1",
"data": { "report_id": "f4c1…", "brand_id": "a1b2…", "status": "completed" }
}A push, not a poll
Register an endpoint once and pick the moments you care about. The second a report or a scheduled run finishes, we tell your systems, and keep trying until they hear it.
Point it at Slack, your warehouse loader, or your client dashboards, and they update on their own the moment new AI answers land.
- When The moment the work is done
- Proof Signed, so you know it came from us
- If you are down We retry, then email you
- Setup The dashboard, or one API call per endpoint
The moments worth reacting to
A report is ready
Refresh the client dashboard, post the new visibility score to Slack, or load the answers into your warehouse.
A report failed
Alert the team before a client notices, and rerun it without anyone checking by hand.
A scheduled run finished
Send the weekly numbers to every stakeholder the minute they exist, with nothing to trigger.
A scheduled run failed
Know why it stopped and fix it before the next report is due.
A location’s Maps rank drops
When a scheduled Maps scan finds a location slipping past your alert, open a ticket, warn the client, or post it to Slack.
An article goes live, changes or comes down
Rebuild a static site, tell an editor, or post the link to Slack or Discord.
Website autopilot changes a page or measures one
Post each change that goes live, and what it did weeks later, to Slack or your own log.
A wave of new pages is written
Tell whoever reviews them the moment the pages are ready to approve.
A lead arrives from your widget
On Agency Plus, every new lead and its report reach your CRM the moment they happen.
A prospect’s report is ready or moves stage
On Agency Plus, your CRM stays in step with your pitch pipeline.
Live in two steps
Register an endpoint
curl -X POST https://api.rankprompt.com/v1/brands/$BRAND_ID/webhooks \
-H "Authorization: Bearer $RANKPROMPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.yourbrand.com/webhooks/rankprompt",
"events": ["report.completed", "schedule.run.completed"],
"description": "Production listener"
}' The signing secret comes back exactly once, store it now. Need a key first? Mint one on the Developers page.
Verify the signature
import crypto from "node:crypto";
// Verify the X-RP-Signature header against the RAW request body.
export function isFromRankPrompt(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const signed = parts.t + "." + rawBody;
const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex");
// Constant-time compare against v1 (also accept v0 during a secret rotation).
const match = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
// Reject replays: require a recent timestamp (within 5 minutes).
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return match && fresh;
} Always sign over the raw request body, before any JSON parsing, and compare in constant time. During a secret rotation, also check the v0 signature.
Plan
Webhooks are included on every Starter plan and up, or on a standalone API plan. It is the same entitlement as the public /v1 API and the MCP server.
Webhook questions
Still have questions? Contact our team
How are webhooks different from polling the API?
You stop polling report status from a worker. Rank Prompt POSTs to your endpoint the moment a report or scheduled run reaches a terminal state, so your stack reacts in seconds instead of on a cron.
Which events can I subscribe to?
Reports and scheduled runs that finish or fail, and a location whose Maps rank drops, from the dashboard or the API. Articles that go live, change or come down, Website autopilot changes, measurements and new pages, widget leads and prospect updates are set up in the dashboard. Each endpoint subscribes only to the ones it needs.
How do I verify a request really came from Rank Prompt?
Every request is signed with your endpoint's secret. A few lines of code check the signature and reject anything that does not match; the snippet above and the webhooks docs show how.
What is in the payload?
A small envelope with the event type and the ids involved. Fetch the full report from the API when you need the detail.
What happens if my endpoint is down?
We keep retrying for about a day. If an endpoint keeps failing, we pause it and email the brand owner, and you turn it back on once it is fixed.
How do I rotate the signing secret?
Rotate it any time from the dashboard or the API. The old secret keeps working for a day, so nothing breaks while you switch.
Can the same event be delivered twice?
Rarely, yes. Each event carries its own id, so your handler can skip one it has already seen.
What plan do I need?
Webhooks are included on every Starter plan and up, or on a standalone API plan. Unlike the /v1 API and the MCP server, which every plan can use, webhooks start at Starter.
Wire Rank Prompt into your stack
Try a paid plan free for 7 days, register an endpoint, and let report and schedule events flow straight into your dashboards, warehouse, and alerts.