Kein Polling mehr. Wir senden an 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.
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" }
} Signiert mit HMAC-SHA256 · gegen dein Secret verifiziert
Push statt Poll
Registriere einmalig einen Endpoint mit der öffentlichen API und wähle die Ereignisse, die dich interessieren. Wenn ein Bericht oder ein geplanter Lauf einen Endzustand erreicht, senden wir ein signiertes JSON-Envelope per POST an deine URL, mit Wiederholungen, bis es ankommt.
Das Envelope ist bewusst klein: Es trägt den Ereignistyp und die IDs, die du brauchst, um die vollständige Ressource per GET von /v1 abzurufen. Es gibt keinen In-App-Schalter, Webhooks werden vollständig über die API verwaltet.
- transport
- HTTPS POST (nur öffentliche URLs)
- Signatur
- X-RP-Signature · HMAC-SHA256
- Ereignisse
- 4 Typen · Bericht & Zeitplan
- Zustellung
- mindestens einmal · wiederholt · wiederholbar
Vier Ereignisse, nur Endzustände
Wir senden, wenn Arbeit wirklich fertig ist, abgeschlossen oder fehlgeschlagen, sowohl für Berichte auf Anfrage als auch für geplante Läufe. Keine lauten Fortschritts-Pings.
report.completed Ein manueller oder geplanter Bericht hat die Analyse beendet. Trägt report_id, brand_id, status und Prompt-Zahlen.
report.failed Ein Berichtslauf ist vor Abschluss fehlgeschlagen. Trägt report_id, brand_id und status.
schedule.run.completed Ein geplanter Batch ist fertig. Trägt scheduled_run_id, scheduled_report_id, brand_id und Regionszahlen.
schedule.run.failed Ein geplanter Batch ist fehlgeschlagen. Enthält einen failure_reason, wenn verfügbar.
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://your-app.com/webhooks/rankprompt",
"events": ["report.completed", "schedule.run.completed"],
"description": "Production listener"
}'
# 201 Created. The signing secret is shown exactly once, so store it now:
# { "id": "whk_…", "secret": "whsec_…", "secret_version": 1, "is_active": true } 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.
Ein vorhersehbares Envelope
Jedes Ereignis kommt in derselben Envelope-Form. Der data-Block trägt die IDs; hol dir die vollständige Ressource von /v1, wenn du mehr brauchst.
{
"id": "evt_9b2c7e1f4a8d4c0e9f2b6a1d3c5e7f90",
"type": "report.completed",
"api_version": "v1",
"created_at": "2026-06-29T12:00:00.482913+00:00",
"data": {
"report_id": "f4c1e2a0-1b2c-3d4e-5f60-7a8b9c0d1e2f",
"brand_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"scheduled_report_id": null,
"status": "completed",
"total_prompts_count": 24,
"ranked_prompts_count": 24
}
} Request-Header
- X-RP-Event
- Der Ereignistyp, z. B. report.completed.
- X-RP-Event-Id
- Stabile ID für das logische Ereignis (evt_…). Dedupliziere darüber.
- X-RP-Delivery-Id
- Eindeutige ID für diesen einzelnen Zustellversuch.
- X-RP-Signature
- Zeitstempel + HMAC-SHA256: t=…,v1=… (und v0=… während der Rotation).
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.
Fragen zu Webhooks
Alles, was Teams vor dem Einrichten eines Endpoints fragen. Schreib uns, wenn deine Frage nicht dabei ist.
Wie unterscheiden sich Webhooks vom Polling der API?
Wie verifiziere ich, dass eine Anfrage wirklich von Rank Prompt kommt?
Was passiert, wenn mein Endpoint down ist?
Kann dasselbe Ereignis zweimal zugestellt werden?
Welche Ereignisse kann ich abonnieren?
Was steht in der Payload?
Wie rotiere ich das Signing-Secret?
Welchen Tarif brauche ich?
Noch Fragen? Schreib unserem Team
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.