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.

Payloads signés HMAC Nouvelles tentatives automatiques Aucun polling
Webhooks · En direct
Livraison entrante http En direct
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

Comment ça marche

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
Événements

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.

Démarrage rapide

Opérationnel en deux étapes

Enregistrez un point de terminaison, puis vérifiez la signature à chaque requête. C’est toute l’intégration.

1

Enregistrez un point de terminaison

Créer un webhook 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 }

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.

2

Vérifiez la signature

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;
}

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.

Payload

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.

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
  }
}

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).
Fiabilité

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.

Voir les forfaits

Gérez les points de terminaison avec la portée write:webhooks ; inspectez les livraisons avec read:webhooks.

FAQ

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 ?
Vous arrêtez de faire du polling sur le statut d’un rapport depuis un worker. Rank Prompt envoie un POST à votre point de terminaison dès qu’un rapport ou une exécution planifiée atteint un état final, si bien que votre stack réagit en quelques secondes plutôt que selon un cron.
Comment vérifier qu’une requête vient vraiment de Rank Prompt ?
Chaque requête porte un en-tête X-RP-Signature de la forme t=<horodatage>,v1=<hmac>. Recalculez un HMAC-SHA256 de « {horodatage}.{corps brut} » avec votre secret de signature et comparez-le à v1 en temps constant. Rejetez les horodatages périmés pour empêcher les rejeux.
Que se passe-t-il si mon point de terminaison est en panne ?
Nous réessayons avec un backoff exponentiel (30s, 2m, 10m, 1h, 6h, 24h) jusqu’à sept tentatives. Après 20 livraisons échouées consécutives, le point de terminaison se désactive automatiquement et nous envoyons un e-mail au propriétaire de la marque. Corrigez, puis réactivez avec un PATCH.
Le même événement peut-il être livré deux fois ?
Oui. La livraison est au moins une fois après succès, alors concevez en conséquence : dédupliquez sur l’identifiant de l’événement (X-RP-Event-Id) et rendez votre gestionnaire idempotent. Les livraisons vers un même point de terminaison préservent l’ordre.
À quels événements puis-je m’abonner ?
Quatre : report.completed, report.failed, schedule.run.completed et schedule.run.failed. Vous pouvez exploiter jusqu’à 5 points de terminaison actifs par marque, chacun abonné à n’importe quel sous-ensemble d’événements.
Que contient le payload ?
Une petite enveloppe JSON : id (evt_…), type, api_version, created_at et un bloc data. Le bloc data porte les identifiants (report_id, brand_id, …) ; récupérez la ressource complète depuis /v1 quand vous avez besoin du détail.
Comment faire tourner le secret de signature ?
Envoyez un POST vers la route de rotation de secret du point de terminaison. Le nouveau secret est renvoyé une seule fois et l’ancien continue de signer les livraisons en tant que v0 pendant un recouvrement de 24 heures, ce qui vous permet de mettre à jour votre vérificateur sans aucune interruption.
De quel forfait ai-je besoin ?
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.

Encore des questions ? Contactez notre équipe

Webhooks · en direct

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.