Kein Polling mehr: Wir benachrichtigen dich.
Abonniere einen HTTPS-Endpoint, und Rank Prompt sendet ein POST, sobald ein Bericht oder ein geplanter Durchlauf bei ChatGPT, Perplexity, Google AI Mode, Claude, Gemini, Muse und Grok fertig ist.
- HMAC-signierte Payloads
- Automatische Wiederholungen
- Kein 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" }
}Push statt Poll
Du registrierst einmal einen Endpoint und wählst die Momente, die dir wichtig sind. Sobald ein Bericht oder ein geplanter Durchlauf fertig ist, sagen wir es deinen Systemen, und versuchen es weiter, bis sie es hören.
Richte ihn auf Slack, deinen Warehouse-Import oder die Dashboards deiner Kunden, und sie aktualisieren sich von selbst, sobald neue KI-Antworten da sind. Du legst sie unter Entwickler > API > Webhooks an, rotierst, prüfst und wiederholst sie dort, oder über die API, damit sie im Code neben dem Rest deines Stacks liegen.
- Wann Sobald die Arbeit erledigt ist
- Nachweis Signiert, damit du weißt, dass es von uns kommt
- Wenn dein Server nicht erreichbar ist Wir versuchen es erneut und mailen dir dann
- Einrichtung Das Dashboard, oder ein API-Aufruf pro Endpoint
Acht Momente, auf die du reagierst
Ein Bericht ist fertig
Aktualisiere das Kunden-Dashboard, poste den neuen Sichtbarkeitswert in Slack oder lade die Antworten in dein Warehouse.
Ein Bericht ist fehlgeschlagen
Alarmiere das Team, bevor der Kunde es merkt, und starte ihn neu, ohne dass jemand von Hand prüft.
Ein geplanter Durchlauf ist fertig
Schick die Wochenzahlen an alle Beteiligten, sobald sie existieren, ohne etwas auszulösen.
Ein geplanter Durchlauf ist fehlgeschlagen
Erfahre, warum er gestoppt hat, und behebe es vor dem nächsten Bericht.
Das Maps-Ranking eines Standorts fällt
local_rank.dropped kommt, wenn ein geplanter Maps-Scan zeigt, dass das durchschnittliche Ranking eines Standorts oder sein Top-3-Anteil über deine Warnschwelle gefallen ist: Ticket öffnen, den Kunden warnen oder es in Slack posten.
Ein Artikel geht live, ändert sich oder wird entfernt
article.published, article.updated und article.unpublished, im Dashboard eingerichtet: baue eine statische Website neu, informiere eine Redaktion oder poste den Link in Slack oder Discord.
Ein Lead kommt über dein Widget
Auf Agency Plus gehen lead.created, lead.report_ready, lead.report_failed und lead.claimed in dem Moment an dein CRM, in dem sie passieren. Eingerichtet im Dashboard.
Der Report eines Prospects ist fertig oder wechselt die Phase
Auf Agency Plus halten prospect.report_ready und prospect.stage_changed dein CRM im Takt mit deiner Akquise-Pipeline. Eingerichtet im Dashboard.
In zwei Schritten live
Einen Endpoint registrieren
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"
}' Das Signing-Secret kommt genau einmal zurück, speichere es jetzt. Brauchst du erst einen Schlüssel? Erstelle einen auf der Entwickler-Seite.
Die Signatur verifizieren
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;
} Signiere immer über den rohen Request-Body, vor jedem JSON-Parsing, und vergleiche in konstanter Zeit. Prüfe während einer Secret-Rotation auch die v0-Signatur.
Gebaut zum Zustellen, und zum Verifizieren
Automatische Wiederholungen
Fehlgeschlagene Zustellungen wiederholen mit Backoff 30s → 2m → 10m → 1h → 6h → 24h: bis zu sieben Versuche, bevor eine Zustellung verworfen wird.
Auto-Deaktivierung + Alarm
Nach 20 aufeinanderfolgenden Fehlern deaktivieren wir den Endpoint und mailen den Markeninhaber. Reaktiviere ihn mit einem PATCH, sobald er behoben ist.
Mindestens einmalige Zustellung
Zustellungen erfolgen nach dem Prinzip „mindestens einmal“. Dedupliziere über X-RP-Event-Id und halte Handler idempotent. Die Reihenfolge pro Endpoint bleibt erhalten.
Rotation ohne Ausfallzeit
Rotiere das Signing-Secret jederzeit. Das alte Secret signiert 24h lang weiter als v0, sodass du deinen Verifier ohne Lücke aktualisierst.
Zustellprotokoll & Replay
Sieh dir aktuelle Versuche an (Status, Antwortcode, Fehler) und wiederhole jede vergangene Zustellung direkt über die API.
Nur öffentliches HTTPS
Endpoints müssen öffentliche https://-URLs sein. Private, Loopback- und nicht routbare Ziele werden abgelehnt (SSRF-Schutz).
Tarif
Webhooks sind in jedem Starter-Tarif und höher enthalten, oder in einem eigenständigen API-Tarif. Es ist dieselbe Berechtigung wie die öffentliche /v1-API und der MCP-Server.
Verwalte Endpoints mit dem Scope write:webhooks; sieh dir Zustellungen an mit read:webhooks.
Fragen zu Webhooks
Noch Fragen? Schreib unserem Team
Wie unterscheiden sich Webhooks vom Polling der API?
Du hörst auf, den Berichtsstatus von einem Worker aus zu pollen. Rank Prompt sendet ein POST an deinen Endpoint, sobald ein Bericht oder geplanter Durchlauf einen Endzustand erreicht, sodass dein Stack in Sekunden statt nach einem Cron reagiert.
Welche Ereignisse kann ich abonnieren?
Fünf: report.completed, report.failed, schedule.run.completed, schedule.run.failed und local_rank.dropped. Du kannst bis zu 5 aktive Endpoints pro Marke betreiben, jeder mit einer beliebigen Teilmenge der Ereignisse.
Wie verifiziere ich, dass eine Anfrage wirklich von Rank Prompt kommt?
Jede Anfrage trägt einen X-RP-Signature-Header der Form t=<timestamp>,v1=<hmac>. Berechne einen HMAC-SHA256 von "{timestamp}.{roher Body}" mit deinem Signing-Secret neu und vergleiche ihn in konstanter Zeit mit v1. Lehne veraltete Zeitstempel ab, um Replays zu verhindern.
Was steht in der Payload?
Ein kleines JSON-Envelope: id (evt_…), type, api_version, created_at und ein data-Block. Der data-Block trägt die IDs (report_id, brand_id, …); hol dir die vollständige Ressource von /v1, wenn du das Detail brauchst.
Was passiert, wenn mein Endpoint nicht erreichbar ist?
Wir wiederholen mit exponentiellem Backoff (30s, 2m, 10m, 1h, 6h, 24h) für bis zu sieben Versuche. Nach 20 aufeinanderfolgenden fehlgeschlagenen Zustellungen deaktiviert sich der Endpoint automatisch, und wir mailen den Markeninhaber. Behebe es und reaktiviere mit einem PATCH.
Wie rotiere ich das Signing-Secret?
Sende ein POST an die secret-rotations-Route des Endpoints. Das neue Secret wird einmal zurückgegeben, und das alte signiert Zustellungen 24 Stunden lang weiter als v0, sodass du deinen Verifier ohne Ausfallzeit aktualisieren kannst.
Kann dasselbe Ereignis zweimal zugestellt werden?
Ja. Zustellungen erfolgen nach dem Prinzip „mindestens einmal“, plane also dafür: dedupliziere über die Ereignis-ID (X-RP-Event-Id) und mache deinen Handler idempotent. Zustellungen an einen einzelnen Endpoint behalten die Reihenfolge bei.
Welchen Tarif brauche ich?
Webhooks sind in jedem Starter-Tarif und höher enthalten, oder in einem eigenständigen API-Tarif. Anders als die /v1-API und der MCP-Server, die jeder Tarif nutzen kann, beginnen Webhooks bei Starter.
Verbinde Rank Prompt mit deinem Stack
Wähle einen Tarif, registriere einen Endpoint und lass Bericht- und Zeitplan-Ereignisse direkt in deine Dashboards, dein Warehouse und deine Alarme fließen.