Webhooks des routines

Un webhook lance une routine quand un autre service (Zapier, Make, n8n, un script, votre propre serveur) envoie une requête signée à son adresse. Le corps JSON de la requête est transmis à la routine avec son prompt, comme une donnée. La requête répond tout de suite ; l’exécution se fait ensuite, et son résultat arrive dans la conversation de la routine.

Créer un déclencheur#Lien vers la section Créer un déclencheur

1. Ouvrez la routine dans « Routines », puis l’onglet « Webhooks ».
2. Cliquez sur « Créer un déclencheur webhook ». Le « Nom » est facultatif : il sert à distinguer vos déclencheurs, par exemple « Zapier nouveaux prospects ».
3. Copiez l’« URL du webhook » et la « Clé de signature ».
4. Cliquez sur « J’ai enregistré la clé ».

« Voir un exemple d’appel » affiche une commande prête à copier avec votre adresse et votre clé.

Chaque routine peut avoir jusqu’à 5 déclencheurs. L’onglet « Webhooks » indique combien d’appels chaque déclencheur accepte par minute et par jour : le nombre par jour dépend du forfait du workspace (voir les formules).

Référence du point d’accès#Lien vers la section Référence du point d’accès

POST /api/v1/routines/hooks/{identifiant}#Lien vers la section POST /api/v1/routines/hooks/{identifiant}

Lance une exécution de la routine liée au déclencheur.

Paramètres#Lien vers la section Paramètres

Réponse#Lien vers la section Réponse

Une requête acceptée répond 202 avant que la routine ne s’exécute :

{"run_id": "4b0c1f0e-2a7d-4c41-9e3b-6f1d2c8a5b90", "status": "queued"}

L’exécution apparaît dans l’onglet « Historique » de la routine avec le déclencheur « Webhook ». Gardez l’horloge de la machine qui envoie à l’heure.

La signature#Lien vers la section La signature

La signature est un HMAC-SHA256 :

• la clé est la clé de signature, telle qu’affichée (elle commence par mwk_) ;
• le message est l’horodatage, un point, puis le corps brut, exactement les octets envoyés ;
• le résultat est écrit en hexadécimal minuscule, 64 caractères.

<X-Moon-Timestamp>.<corps brut>

Pour vérifier votre calcul, avec ces valeurs d’exemple :

L’en-tête X-Moon-Signature peut contenir jusqu’à 5 signatures séparées par des virgules (v1=…,v1=…) : la requête est acceptée si l’une d’elles correspond. Une signature sans le préfixe v1= est acceptée aussi.

Exemples#Lien vers la section Exemples

Remplacez l’adresse et la clé par celles de votre déclencheur.

KEY='mwk_votre_cle'
URL='https://chat.realmoon.ai/api/v1/routines/hooks/votre_identifiant'
BODY='{"event":"new_lead","id":"evt_123"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$KEY" -hex | sed 's/^.* //')
curl -sS -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H "X-Moon-Timestamp: $TS" \
  -H "X-Moon-Signature: v1=$SIG" \
  --data-binary "$BODY"

import hashlib, hmac, json, time, requests

key = "mwk_votre_cle"
url = "https://chat.realmoon.ai/api/v1/routines/hooks/votre_identifiant"
body = json.dumps({"event": "new_lead", "id": "evt_123"}).encode()
ts = str(int(time.time()))
sig = hmac.new(key.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()

r = requests.post(url, data=body, headers={
    "Content-Type": "application/json",
    "X-Moon-Timestamp": ts,
    "X-Moon-Signature": f"v1={sig}",
})
print(r.status_code, r.json())

import { createHmac } from 'node:crypto';

const key = 'mwk_votre_cle';
const url = 'https://chat.realmoon.ai/api/v1/routines/hooks/votre_identifiant';
const body = JSON.stringify({ event: 'new_lead', id: 'evt_123' });
const ts = Math.floor(Date.now() / 1000).toString();
const sig = createHmac('sha256', key).update(`${ts}.${body}`).digest('hex');

const res = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Moon-Timestamp': ts,
    'X-Moon-Signature': `v1=${sig}`
  },
  body
});
console.log(res.status, await res.json());

En Python, passez le corps déjà encodé dans data= (et non json=), pour envoyer les octets signés. L’exemple JavaScript tourne avec Node.js 18 ou plus récent.

Dans Zapier, Make ou n8n, utilisez une étape de code ou de requête HTTP qui calcule la signature sur le corps exact, puis l’envoie avec les deux en-têtes.

Erreurs#Lien vers la section Erreurs

Le corps d’une erreur a la forme {"detail": …}. Le détail est soit un texte, soit un objet {"code": …, "message": …}.

Exemples de corps :

{"detail": "Introuvable."}

{"detail": {"code": "rate_limited", "message": "Limite de ce déclencheur atteinte."}}

Le même 404 répond pour toutes les causes listées, pour ne rien révéler de l’existence d’un déclencheur. Vérifiez d’abord l’adresse, la clé et le calcul de la signature.

Renvoyer une requête#Lien vers la section Renvoyer une requête

• Une requête refusée par 429, 403 ou 503 ne compte pas dans les limites du déclencheur. Vous pouvez la renvoyer telle quelle tant que son horodatage a moins de 5 minutes, ou la signer de nouveau avec une heure récente.
• Deux requêtes identiques (même corps, même seconde) ont la même signature : la seconde reçoit 409. Ajoutez un identifiant d’événement unique au corps, par exemple "id": "evt_123".
• Une requête acceptée n’est jamais exécutée deux fois, même renvoyée.

Ce que fait la routine#Lien vers la section Ce que fait la routine

La routine reçoit son prompt, suivi du corps de la requête présenté comme des données envoyées par un service externe. L’IA s’en sert comme matière pour la tâche, sans suivre les instructions qu’il pourrait contenir. Le corps passe par Moon Blur comme le reste de la requête.

Une exécution lancée par un webhook :

• n’agit jamais dans vos connecteurs (aucun e-mail envoyé, aucun message publié), même si la routine a l’option « Autoriser les actions » ;
• n’ouvre pas de page web, n’exécute pas de code, ne génère ni image ni vidéo ;
• ne crée pas de lien public vers vos fichiers et n’en joint pas à un message ;
• peut lire vos connecteurs et chercher sur le web ;
• n’est pas relancée automatiquement en cas d’erreur ;
• compte dans votre limite d’utilisation comme une exécution normale.

Le prompt et la réponse sont marqués comme contenant un contenu extérieur : rien de distant ne se charge dans la réponse sans votre clic. Tant que ce message reste dans la conversation, les tours suivants gardent les mêmes précautions : chaque action dans vos outils demande votre validation.

Gérer les déclencheurs#Lien vers la section Gérer les déclencheurs

Désactiver un déclencheur, renouveler sa clé ou le supprimer annule aussi ses exécutions en file qui n’ont pas encore démarré. La liste montre pour chaque déclencheur les « Appels reçus » et la date du dernier appel. Supprimer la routine supprime ses déclencheurs.

Voir aussi#Lien vers la section Voir aussi

• Routines
• Messageries et déclencheurs