Webhook de déclenchement de routine
Lancez une routine depuis vos propres systèmes. L'adresse, les cinq modes de signature, les en-têtes, la charge utile, les réponses, les relances et la protection anti-rejeu, avec du code de signature en curl, JavaScript et Python.
Un déclencheur webhook permet à n'importe quel système de lancer une routine : une alerte de supervision, un pipeline de CI, un formulaire, un autre produit. Chaque livraison crée une exécution ; le JSON envoyé est stocké sur l'exécution et présenté à l'agent comme des données.
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fireMise en place
- Ouvrez la routine, puis Triggers › Add trigger › Webhook.
- Choisissez un mode de signature (ci-dessous). Démarrez le déclencheur en mode test (
setupPending: truedans l'API) pendant que vous configurez l'émetteur. - Copiez l'URL et le secret. Le secret n'est affiché qu'une fois ; Rotate secret en génère un nouveau et l'ancien cesse aussitôt de fonctionner.
- Envoyez une livraison de test. En mode test, elle est vérifiée et enregistrée mais ne lance aucune exécution : vous pouvez confirmer l'authentification sans risque.
- Désactivez le mode test. Désormais, chaque livraison acceptée lance une exécution.
Modes de signature
| Mode | Envoyer | Le choisir quand |
|---|---|---|
bearer (par défaut) |
Authorization: Bearer <secret> |
Votre émetteur peut définir un en-tête. |
hmac_sha256 |
X-Veyra-Timestamp et X-Veyra-Signature |
Vous voulez des requêtes signées, limitées dans le temps et impossibles à rejouer. |
github_hmac |
X-Hub-Signature-256: sha256=<hex> |
L'émetteur signe comme GitHub ou Sentry (HMAC du corps brut). |
app_webhook |
Bearer, ou X-Hub-Signature-256 |
Une application connectée livre des événements ; la charge utile est transmise à l'agent. |
none |
Rien | Seules des personnes peuvent le choisir ; l'URL seule fait office de secret. Les agents ne peuvent pas créer de déclencheurs non authentifiés. |
hmac_sha256
Calculez la signature sur l'horodatage, un point, puis les octets exacts du corps :
signature = hex( HMAC-SHA256( secret, timestamp + "." + raw_body ) )Envoyez X-Veyra-Timestamp: <timestamp> (secondes ou millisecondes Unix) et X-Veyra-Signature: sha256=<signature>. Un horodatage hors de la fenêtre anti-rejeu du déclencheur (300 secondes, sauf si vous choisissez entre 30 et 86 400) est refusé, et une même requête signée n'est acceptée qu'une fois.
En-têtes
| En-tête | Obligatoire | Signification |
|---|---|---|
Content-Type: application/json |
Oui | Le corps doit être un objet JSON. |
Authorization |
bearer, app_webhook |
Bearer <secret>. |
X-Veyra-Timestamp |
hmac_sha256 |
L'heure Unix de la signature. |
X-Veyra-Signature |
hmac_sha256 |
sha256= suivi du HMAC en hexadécimal. Accepté aussi pour github_hmac. |
X-Hub-Signature-256 |
github_hmac |
sha256= suivi du HMAC hexadécimal du corps brut. |
Idempotency-Key |
Recommandé | Votre identifiant pour cet événement. Une répétition renvoie le premier résultat. X-GitHub-Delivery est utilisé s'il est présent. |
X-Veyra-Idempotency-Scope |
Non | trigger (par défaut) : les clés sont uniques par déclencheur. routine : uniques sur tous les déclencheurs de la routine. |
Corps
N'importe quel objet JSON, jusqu'à 10 Mo. Deux champs ont un sens particulier :
variables: un objet de valeurs pour les variables de la routine, par exemple{"variables": {"ticket": "SUP-812"}}.- Tout le reste est stocké sur l'exécution comme charge utile.
Envoyer une requête signée
URL="https://intelligence-api.veyra.so/api/routine-triggers/public/$PUBLIC_ID/fire"
BODY='{"variables":{"ticket":"SUP-812"},"severity":"high"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$TRIGGER_SECRET" -hex | sed 's/^.* //')
curl -X POST "$URL" \
-H "Content-Type: application/json" \
-H "X-Veyra-Timestamp: $TS" \
-H "X-Veyra-Signature: sha256=$SIG" \
-H "Idempotency-Key: SUP-812" \
--data-binary "$BODY"import { createHmac } from "node:crypto";
const body = JSON.stringify({ variables: { ticket: "SUP-812" }, severity: "high" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", process.env.VEYRA_TRIGGER_SECRET)
.update(`${timestamp}.`)
.update(body)
.digest("hex");
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Veyra-Timestamp": timestamp,
"X-Veyra-Signature": `sha256=${signature}`,
"Idempotency-Key": "SUP-812",
},
body, // envoyez exactement les octets signés
});
console.log(response.status, await response.json());import hashlib, hmac, json, os, time
import requests
secret = os.environ["VEYRA_TRIGGER_SECRET"].encode()
body = json.dumps({"variables": {"ticket": "SUP-812"}, "severity": "high"}, separators=(",", ":")).encode()
timestamp = str(int(time.time()))
signature = hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
response = requests.post(
url,
data=body, # envoyez exactement les octets signés
headers={
"Content-Type": "application/json",
"X-Veyra-Timestamp": timestamp,
"X-Veyra-Signature": f"sha256={signature}",
"Idempotency-Key": "SUP-812",
},
timeout=15,
)
print(response.status_code, response.json())Avec bearer, envoyez seulement Authorization: Bearer $TRIGGER_SECRET et le JSON.
Réponses
| Statut | Corps | Signification |
|---|---|---|
202 |
L'exécution de la routine | Acceptée. Le status de l'exécution indique ce qui s'est passé (par exemple une tâche a été créée, ou la livraison a été fusionnée avec une exécution en cours). |
202 |
{"status": "test_received", "test": true} |
Mode test : authentifiée et enregistrée, aucune exécution lancée. |
202 |
{"status": "ignored"} |
Une application connectée a envoyé un événement auquel le déclencheur n'est pas abonné. |
400 |
{"error": ...} |
Le corps n'est pas un objet JSON, ou un en-tête a une valeur incorrecte. |
401 |
{"error": ...} |
Secret ou signature absent ou incorrect, ou horodatage hors de la fenêtre. |
404 |
{"error": ...} |
Ce déclencheur n'existe pas. |
409 |
{"error": ...} |
La routine est archivée, ou le déclencheur ou la routine n'est pas actif. |
415 |
{"error": ...} |
Content-Type n'est pas application/json. |
Les livraisons rejetées sont enregistrées sur le déclencheur (last delivery: rejected) et dans le journal d'activité : vous voyez les tentatives échouées sans exposer ce qui a été envoyé.
Relances et doublons
- Relancez après une erreur réseau, un délai dépassé, un
429ou un5xx, avec la mêmeIdempotency-Key. Une clé répétée renvoie le premier résultat au lieu d'une seconde exécution. - Avec
hmac_sha256, signez de nouveau chaque relance avec un horodatage neuf ; l'anti-rejeu s'applique par signature. - Ne relancez pas les réponses
4xxautres que429; corrigez plutôt la requête.
Ce que voit l'agent
La tâche de l'exécution contient la demande de la routine. La charge utile envoyée y est jointe comme données, marquée comme venant de l'extérieur et à ne pas suivre comme des instructions. Donnez à la routine des instructions claires sur la façon de traiter la charge utile.
Voir Fire a public routine trigger, Create a routine trigger et Rotate a routine trigger secret dans la référence de l'API.