Kein Polling mehr: Wir benachrichtigen dich.
Abonniere einen HTTPS-Endpoint, und Rank Prompt sendet ein POST, sobald ein Bericht oder ein geplanter Lauf bei ChatGPT, Perplexity, Google AI Mode, Claude, Gemini und Grok fertig ist. Signiert, wiederholt und wiederholbar, damit deine Dashboards, dein Warehouse und deine Alarme in Sekunden reagieren, nicht nach einem Cron.
- 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" }
}So funktioniert es
Push statt Poll
Du registrierst einmal einen Endpoint und wählst die Momente, die dir wichtig sind. Sobald ein Bericht oder ein geplanter Lauf 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 Developers > Webhooks an, rotierst, prüfst und wiederholst sie dort, oder über die API, damit sie im Code neben dem Rest deines Stacks leben.
- wann Sobald die Arbeit erledigt ist
- Nachweis Signiert, damit du weißt, dass es von uns kommt
- wenn du down bist Wir versuchen es erneut und mailen dir dann
- Einrichtung Das Dashboard, oder ein API-Aufruf pro Endpoint
Sechs Momente, auf die du reagierst
Wir melden uns nur, wenn die Arbeit erledigt ist: Berichte, die du startest, und geplante, Artikel, die du veröffentlichst, und auf Agency Plus die Leads, die dein Widget bringt. Keine lauten Fortschrittsmeldungen.
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 Lauf ist fertig
Schick die Wochenzahlen an alle Beteiligten, sobald sie existieren, ohne etwas auszulösen.
Ein geplanter Lauf ist fehlgeschlagen
Erfahre, warum er gestoppt hat, und behebe es vor dem nächsten Bericht.
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.
In zwei Schritten live
Registriere einen Endpoint und verifiziere dann die Signatur bei jeder Anfrage. Das ist die ganze Integration.
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 Key? 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
Wiederholungen, Auto-Deaktivierung, Idempotenz und signierte Rotation, damit ein instabiler Endpoint dir nie ein Ereignis kostet und ein geleaktes Secret nie Ausfallzeit verursacht.
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
Zustellung ist nach Erfolg 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 dasselbe Entitlement wie die öffentliche /v1-API und der MCP-Server.
Verwalte Endpoints mit dem Scope write:webhooks; sieh dir Zustellungen an mit read:webhooks.
FAQ
Fragen zu Webhooks
Alles, was Teams vor dem Einrichten eines Endpoints fragen. Schreib uns, wenn deine Frage nicht dabei ist.
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 Lauf einen Endzustand erreicht, sodass dein Stack in Sekunden statt nach einem Cron reagiert.
Welche Ereignisse kann ich abonnieren?
Vier: report.completed, report.failed, schedule.run.completed und schedule.run.failed. 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 down 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. Zustellung ist nach Erfolg 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.
Erst dein kostenloser KI-Sichtbarkeitsbericht · 7 Tage Testphase in jedem Tarif
Verbinde Rank Prompt mit deinem Stack
Starte eine kostenlose Testphase, registriere einen Endpoint und lass Bericht- und Zeitplan-Ereignisse direkt in deine Dashboards, dein Warehouse und deine Alarme fließen.