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, and Grok. Signed, retried, and replayable, so your dashboards, warehouse, and alerts react in seconds, not on a cron.

Create a webhook Read the docs

HMAC-signed payloads
Automatic retries
No polling

Incoming delivery

POST /webhooks/rankprompt HTTP/1.1
Host: your-app.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" }
}

How it works

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. Create, rotate, inspect and replay them in Developers > Webhooks, or over the API, so they can live in code next to the rest of your stack.

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

Events

Four moments worth reacting to

We only speak up when the work is done, for reports you run and for scheduled ones. No noisy progress pings.

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.

Quickstart

Live in two steps

Register an endpoint

Create a webhook

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://your-app.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

verify.ts

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.

Reliability

Built to deliver, and to verify

Retries, auto-disable, idempotency, and signed rotation, so a flaky endpoint never loses you an event and a leaked secret never costs you downtime.

Automatic retries

Failed deliveries retry on a 30s → 2m → 10m → 1h → 6h → 24h backoff: up to seven attempts before a delivery is dropped.

Auto-disable + alert

After 20 consecutive failures we disable the endpoint and email the brand owner. Re-enable it with one PATCH once it’s fixed.

At-least-once delivery

Delivery is at-least-once after success. Dedupe on X-RP-Event-Id and keep handlers idempotent. Per-endpoint order is preserved.

Zero-downtime rotation

Rotate the signing secret anytime. The old secret keeps signing as v0 for 24h, so you roll your verifier with no gap.

Delivery log & replay

Inspect recent attempts (status, response code, error) and replay any past delivery straight from the API.

Public HTTPS only

Endpoints must be public https:// URLs. Private, loopback, and non-routable targets are rejected (SSRF guard).

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.

See plans

Manage endpoints with the write:webhooks scope; inspect deliveries with read:webhooks.

FAQ

Webhook questions

Everything teams ask before they wire up an endpoint. Email us if your question isn't covered.

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?

Four: report.completed, report.failed, schedule.run.completed, and schedule.run.failed. You can run up to 5 active endpoints per brand, each subscribing to any subset of events.

How do I verify a request really came from Rank Prompt?

Every request carries an X-RP-Signature header of the form t=<timestamp>,v1=<hmac>. Recompute an HMAC-SHA256 of "{timestamp}.{raw body}" with your signing secret and compare it to v1 in constant time. Reject stale timestamps to prevent replays.

What is in the payload?

A small JSON envelope: id (evt_…), type, api_version, created_at, and a data block. The data block carries the ids (report_id, brand_id, …); fetch the full resource from /v1 when you need the detail.

What happens if my endpoint is down?

We retry with exponential backoff (30s, 2m, 10m, 1h, 6h, 24h) for up to seven attempts. After 20 consecutive failed deliveries the endpoint auto-disables and we email the brand owner. Fix it, then re-enable with a PATCH.

How do I rotate the signing secret?

POST to the endpoint’s secret-rotations route. The new secret is returned once and the old one keeps signing deliveries as v0 for a 24-hour overlap, so you can roll your verifier with zero downtime.

Can the same event be delivered twice?

Yes. Delivery is at-least-once after success, so design for it: dedupe on the event id (X-RP-Event-Id) and make your handler idempotent. Deliveries to a single endpoint preserve order.

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.

Free AI visibility report first · 7-day trial on any plan

Wire Rank Prompt into your stack

Start a free trial, register an endpoint, and let report and schedule events flow straight into your dashboards, warehouse, and alerts.

Start free trial Read the docs