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.

HMAC-signierte Payloads Automatische Wiederholungen Kein Polling
Webhooks · Live
Eingehende Zustellung http Live
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

So funktioniert es

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
Ereignisse

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.

Schnellstart

In zwei Schritten live

Registriere einen Endpoint und verifiziere dann die Signatur bei jeder Anfrage. Das ist die ganze Integration.

1

Einen Endpoint registrieren

Webhook erstellen bash
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.

2

Die Signatur verifizieren

verify.ts typescript
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.

Payload

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.

report.completed json
{
  "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).
Zuverlässigkeit

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.

Tarife ansehen

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.

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.
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 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.
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.
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.
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.
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.
Welchen Tarif brauche ich?
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.

Noch Fragen? Schreib unserem Team

Webhooks · Live

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.