Arrêtez le polling. Nous vous les envoyons.
Abonnez un point de terminaison HTTPS et Rank Prompt envoie un POST dès qu’un rapport ou une exécution planifiée se termine sur ChatGPT, Perplexity, Google AI Mode, Claude, Gemini et Grok. Signé, retenté et rejouable, pour que vos tableaux de bord, votre entrepôt de données et vos alertes réagissent en quelques secondes, pas selon un 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" }
} Signé avec HMAC-SHA256 · vérifié avec votre secret
Un envoi, pas un sondage
Enregistrez un point de terminaison une seule fois avec l’API publique et choisissez les événements qui vous intéressent. Quand un rapport ou une exécution planifiée atteint un état final, nous envoyons un enveloppe JSON signée en POST vers votre URL, en réessayant jusqu’à ce que ça passe.
L’enveloppe est volontairement petite : elle porte le type d’événement et les identifiants dont vous avez besoin pour GET la ressource complète depuis /v1. Il n’y a pas de bascule dans l’application, les webhooks se gèrent entièrement via l’API.
- transport
- HTTPS POST (URL publiques uniquement)
- signature
- X-RP-Signature · HMAC-SHA256
- événements
- 4 types · rapport et planification
- livraison
- au moins une fois · avec nouvelles tentatives · rejouable
Quatre événements, uniquement des états finaux
Nous émettons quand le travail est réellement terminé, achevé ou en échec, pour les rapports à la demande comme pour les exécutions planifiées. Pas de notifications de progression bruyantes.
report.completed Un rapport manuel ou planifié a terminé son analyse. Porte report_id, brand_id, status et le nombre de prompts.
report.failed Une exécution de rapport a échoué avant de se terminer. Porte report_id, brand_id et status.
schedule.run.completed Un lot planifié s’est terminé. Porte scheduled_run_id, scheduled_report_id, brand_id et les décomptes par région.
schedule.run.failed Un lot planifié a échoué. Inclut un failure_reason quand il est disponible.
Opérationnel en deux étapes
Enregistrez un point de terminaison, puis vérifiez la signature à chaque requête. C’est toute l’intégration.
Enregistrez un point de terminaison
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 } Le secret de signature revient exactement une fois, stockez-le maintenant. Besoin d’une clé d’abord ? Générez-en une sur la page Développeurs.
Vérifiez la signature
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;
} Signez toujours sur le corps de la requête brut, avant tout parsing JSON, et comparez en temps constant. Pendant une rotation du secret, vérifiez aussi la signature v0.
Une enveloppe prévisible
Chaque événement livre la même forme d’enveloppe. Le bloc data porte les identifiants ; récupérez la ressource complète depuis /v1 quand vous avez besoin de plus.
{
"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
}
} En-têtes de la requête
- X-RP-Event
- Le type d’événement, par exemple report.completed.
- X-RP-Event-Id
- Identifiant stable de l’événement logique (evt_…). Dédupliquez dessus.
- X-RP-Delivery-Id
- Identifiant unique pour cette tentative de livraison individuelle.
- X-RP-Signature
- Horodatage + HMAC-SHA256 : t=…,v1=… (et v0=… pendant une rotation).
Conçu pour livrer, et pour vérifier
Nouvelles tentatives, désactivation automatique, idempotence et rotation signée, pour qu’un point de terminaison instable ne vous fasse jamais perdre un événement et qu’un secret divulgué ne vous coûte jamais d’interruption.
Nouvelles tentatives automatiques
Les livraisons échouées sont retentées avec un backoff de 30s → 2m → 10m → 1h → 6h → 24h : jusqu’à sept tentatives avant qu’une livraison soit abandonnée.
Désactivation automatique + alerte
Après 20 échecs consécutifs, nous désactivons le point de terminaison et envoyons un e-mail au propriétaire de la marque. Réactivez-le avec un PATCH une fois corrigé.
Livraison au moins une fois
La livraison est au moins une fois après succès. Dédupliquez sur X-RP-Event-Id et rendez vos gestionnaires idempotents. L’ordre par point de terminaison est préservé.
Rotation sans interruption
Faites tourner le secret de signature à tout moment. L’ancien secret continue de signer en tant que v0 pendant 24h, ce qui vous laisse mettre à jour votre vérificateur sans aucune coupure.
Journal de livraison et rejeu
Inspectez les tentatives récentes (statut, code de réponse, erreur) et rejouez n’importe quelle livraison passée directement depuis l’API.
HTTPS public uniquement
Les points de terminaison doivent être des URL publiques https://. Les cibles privées, loopback et non routables sont rejetées (protection SSRF).
Forfait
Les webhooks sont inclus dans tout forfait Starter et au-dessus, ou dans un forfait API autonome. C’est le même droit d’accès que l’API publique /v1 et le serveur MCP.
Gérez les points de terminaison avec la portée write:webhooks ; inspectez les livraisons avec read:webhooks.
Questions sur les webhooks
Tout ce que les équipes demandent avant de brancher un point de terminaison. Écrivez-nous si votre question n’est pas couverte.
En quoi les webhooks diffèrent-ils du polling de l’API ?
Comment vérifier qu’une requête vient vraiment de Rank Prompt ?
Que se passe-t-il si mon point de terminaison est en panne ?
Le même événement peut-il être livré deux fois ?
À quels événements puis-je m’abonner ?
Que contient le payload ?
Comment faire tourner le secret de signature ?
De quel forfait ai-je besoin ?
Encore des questions ? Contactez notre équipe
D’abord votre rapport de visibilité IA gratuit · essai de 7 jours sur tout forfait
Intégrez Rank Prompt à votre stack
Démarrez un essai gratuit, enregistrez un point de terminaison, et laissez les événements de rapport et de planification circuler directement vers vos tableaux de bord, votre entrepôt de données et vos alertes.