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 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
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" }
}Comment ça marche
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 Developers > 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 email
- installation Le tableau de bord, ou un appel API par point de terminaison
Six moments pour réagir
Nous ne parlons que quand le travail est fini : les rapports que vous lancez et les planifiés, les articles que vous publiez et, sur Agency Plus, les leads que votre widget apporte. Aucune notification de progression superflue.
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.
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.
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://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, 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.
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.
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 ?
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.
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. 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.
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.
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.