Fini le polling : on vous notifie.
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, Muse et Grok.
- Payloads signés HMAC
- Nouvelles tentatives automatiques
- Aucun 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" }
}Un envoi, pas un sondage
Vous enregistrez un point de terminaison une fois et choisissez les moments qui comptent. Dès qu’un rapport ou une exécution planifiée se termine, nous prévenons vos systèmes, et nous insistons jusqu’à ce qu’ils l’entendent.
Branchez-le sur Slack, le chargement de votre entrepôt de données ou les tableaux de bord de vos clients : ils se mettent à jour seuls dès que de nouvelles réponses IA arrivent. Vous les créez, faites tourner leur secret, les inspectez et les rejouez dans Développeurs > Webhooks, ou par API, pour qu’ils vivent dans le code avec le reste de votre stack.
- Quand Dès que le travail est fini
- Preuve Signé, vous savez que ça vient de nous
- Si vous êtes hors ligne Nous réessayons, puis vous prévenons par e-mail
- Installation Le tableau de bord, ou un appel API par point de terminaison
Huit moments pour réagir
Un rapport est prêt
Mettez à jour le tableau de bord du client, publiez le nouveau score de visibilité dans Slack ou chargez les réponses dans votre entrepôt de données.
Un rapport a échoué
Alertez l’équipe avant que le client ne s’en aperçoive, et relancez-le sans vérification manuelle.
Une exécution planifiée est terminée
Envoyez les chiffres de la semaine à chaque intéressé dès qu’ils existent, sans rien déclencher.
Une exécution planifiée a échoué
Sachez pourquoi elle s’est arrêtée et corrigez avant le prochain rapport.
La position Maps d’un établissement baisse
local_rank.dropped arrive quand une analyse Maps planifiée constate que la position moyenne d’un établissement ou sa part dans le top 3 a baissé au-delà de votre alerte : ouvrez un ticket, prévenez le client ou publiez-le sur Slack.
Un article est publié, modifié ou retiré
article.published, article.updated et article.unpublished, configurés dans le tableau de bord : reconstruisez un site statique, prévenez un éditeur ou publiez le lien dans Slack ou Discord.
Un lead arrive par votre widget
Sur Agency Plus, lead.created, lead.report_ready, lead.report_failed et lead.claimed arrivent dans votre CRM au moment où ils se produisent. À configurer dans le tableau de bord.
Le rapport d’un prospect est prêt ou change d’étape
Sur Agency Plus, prospect.report_ready et prospect.stage_changed gardent votre CRM au rythme de votre prospection. À configurer dans le tableau de bord.
Opérationnel en deux étapes
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://api.yourbrand.com/webhooks/rankprompt",
"events": ["report.completed", "schedule.run.completed"],
"description": "Production listener"
}' 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.
Conçu pour livrer, et pour vérifier
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
Chaque événement est livré au moins une fois. 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
Encore des questions ? Contactez notre équipe
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.
À quels événements puis-je m’abonner ?
Cinq : report.completed, report.failed, schedule.run.completed, schedule.run.failed et local_rank.dropped. Vous pouvez exploiter jusqu’à 5 points de terminaison actifs par marque, chacun abonné à n’importe quel sous-ensemble d’événements.
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 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.
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.
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.
Le même événement peut-il être livré deux fois ?
Oui. Chaque événement est livré au moins une fois, 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.
De quel forfait ai-je besoin ?
Les webhooks sont inclus dans tout forfait Starter et au-dessus, ou dans un forfait API autonome. Contrairement à l’API /v1 et au serveur MCP, que tous les forfaits peuvent utiliser, les webhooks commencent à Starter.
Intégrez Rank Prompt à votre stack
Choisissez un forfait, 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.