Webhooks

Les webhooks Gaard vous permettent de recevoir les résultats de classification sous forme de POST HTTP vers votre propre endpoint dès que le traitement est terminé.

Pour les intégrateurs, l’idée principale est simple :

votre système envoie une vidéo à Gaard
Gaard la classifie de manière asynchrone
lorsque le résultat final est disponible, Gaard envoie le JSON du résultat à votre URL de webhook

Ce qu’un webhook envoie

Gaard envoie actuellement un seul type d’événement webhook : le résultat de classification final.

La charge utile du webhook utilise la même forme JSON que le résultat renvoyé par :

GET /api/result/{id}
POST /api/classify?sync=true

Cela signifie que vous pouvez généralement réutiliser le même parseur pour les intégrations par polling et par webhook.

Comment ça fonctionne

Votre application soumet une vidéo à POST /api/classify.
Gaard accepte la tâche et la traite de manière asynchrone.
Une fois la classification terminée et le résultat persisté, Gaard envoie une requête HTTP POST à chaque webhook configuré pour le flux.
Votre endpoint reçoit la charge utile du résultat et peut déclencher des actions en aval telles que la création d’incident, l’enrichissement d’alarme ou l’archivage.

Configurer un webhook dans Gaard

Dans l’application Gaard :

Ouvrez la section des intégrations. Intégrations de la plateforme
Créez une nouvelle intégration Webhook.
Sélectionnez le flux qui doit déclencher le webhook.
Saisissez l’URL de destination de votre récepteur.
Enregistrez l’intégration.
Soumettez une classification de test et vérifiez que votre endpoint reçoit bien la charge utile.

Si vous devez envoyer le même résultat à plusieurs systèmes, créez plusieurs intégrations webhook.

Format de la requête HTTP

Gaard envoie :

Méthode : POST
En-tête : Content-Type: application/json
Corps : JSON du résultat de classification

Gaard n’ajoute pas actuellement d’en-têtes d’authentification personnalisés ni d’en-tête de signature. Si votre récepteur nécessite une authentification, protégez-le à la périphérie, par exemple via un chemin d’URL secret, un reverse proxy ou tout autre mécanisme sous votre contrôle.

Exemple de charge utile

{
  "id": "6662f5c1f897618de43f0bbd",
  "status": {
    "classify": "done",
    "video": "done"
  },
  "parent_id": "000000000000000000000000",
  "camera_id": "134188-VI08",
  "analyse_id": 3373550353,
  "tenant": "tenant",
  "duration": 2968236,
  "duration_seconds": 2,
  "model": "noname",
  "version": "2.0.16123",
  "error_code": 0,
  "error_msg": "",
  "risk": "intrusion",
  "labels": ["intrusion", "person"],
  "result": "classified",
  "scores": {
    "flag": 0.049,
    "plant": 0.03,
    "web": 0.009,
    "NOTHING": 0.0005,
    "intrusion": 0.973,
    "person": 0.973,
    "rain": 0.002,
    "spider": 0.007,
    "text": 0.0006,
    "wind": 0.021,
    "animal": 0.035,
    "other": 0.028,
    "vehicule": 0.101
  },
  "video": {
    "videoname": "video.mov",
    "filename": "video.mov",
    "filesize": 786800,
    "specs": {
      "height": 320,
      "original.width": 640,
      "duration": 4.217772,
      "fps": 3.08,
      "nframes": 13,
      "original.fps": 3,
      "original.height": 360,
      "original.nframes": 12,
      "width": 568
    }
  },
  "metadata": {
    "camera_id": "VI08",
    "site_id": 134188
  },
  "created_at": "2024-05-14T16:13:37.156+02:00",
  "started_at": "2024-05-14T16:13:37.156+02:00"
}

Notes sur les champs de la charge utile

Champ	Type	Notes
`id`	string	Identifiant stable de classification. À utiliser comme clé principale de corrélation.
`status`	object	État final du traitement de la classification et de l’annotation vidéo.
`camera_id`	string	Identifiant de caméra dérivé des métadonnées.
`analyse_id`	int	Identifiant d’analyse d’origine lorsqu’il est fourni par l’émetteur.
`tenant`	string	Tenant Gaard qui a produit le résultat.
`risk`	string	Résultat de haut niveau tel que `safe`, `danger` ou `intrusion`.
`labels`	string[]	Labels dérivés de l’ensemble des scores.
`result`	string	Chaîne brute du moteur, par exemple `classified`.
`scores`	object	Scores de confiance par label.
`video`	object	Nom, taille et specs techniques du fichier vidéo.
`metadata`	object	Métadonnées d’origine soumises avec la requête de classification.
`created_at`	string	Date de création de la tâche de classification.
`started_at`	string	Date de début du traitement.

Pour la référence complète des champs, voir Structure de la réponse et Résultat de classification.

Latence et comportement de livraison

La livraison du webhook est liée à la fin de la classification.

Gaard n’envoie pas le webhook lorsque la tâche n’est que simplement acceptée.
Gaard envoie le webhook après que le résultat de classification est stocké et le post-traitement terminé.
En pratique, le moment d’envoi du webhook est généralement très proche du moment où le résultat devient disponible via GET /api/result/{id}.

Il n’existe pas de file dédiée aux webhooks ni de fenêtre d’envoi par lot. La latence webhook de bout en bout est donc :

Σ(t) = classify + post-traitement + réseau

Gaard ne publie pas actuellement de SLA de latence webhook fixe, car la durée de classification dépend de la vidéo, du modèle, de la charge du runtime et de la distance réseau jusqu’à votre récepteur.

Modèle de fiabilité

La livraison des webhooks fonctionne actuellement en mode « best effort ».

Gaard envoie un POST HTTP par endpoint webhook configuré.
Gaard n’implémente pas actuellement de réessais automatiques.
Gaard ne considère pas actuellement les réponses HTTP non 2xx comme des échecs de livraison à réessayer.

De ce fait, votre récepteur doit :

accepter la requête rapidement
renvoyer une réponse immédiatement après une validation de base
déplacer les traitements lourds vers une file interne ou un worker en arrière-plan
stocker l’id de la charge utile pour garantir l’idempotence

Recommandations pour le récepteur

Pour rendre votre intégration robuste :

Acceptez les requêtes application/json.
Vérifiez que id, tenant et les champs dont vous dépendez sont bien présents.
Utilisez l’id de la charge utile comme clé de déduplication.
Traitez error_code != 0 comme un résultat terminé en erreur, et non comme un échec de transport.
Gardez votre endpoint webhook rapide et asynchrone.
Journalisez la charge utile complète lors du déploiement initial pour confirmer les champs de métadonnées présents dans votre environnement.

Exemple de réponse depuis votre endpoint

Votre endpoint peut renvoyer une réponse de succès minimale telle que :

HTTP/1.1 200 OK
Content-Type: application/json

{"ok":true}

Webhooks ou polling : quand utiliser chaque approche

Utilisez les webhooks lorsque :

vous souhaitez un traitement en aval quasi temps réel
vous exploitez déjà un service HTTP capable de recevoir des callbacks
vous souhaitez éviter le polling répété de la disponibilité du résultat

Utilisez le polling via GET /api/result/{id} lorsque :

les callbacks HTTP entrants ne sont pas possibles dans votre environnement
vous avez besoin d’un contrôle explicite sur le moment de la récupération
vous préférez une première intégration plus simple avant de passer à une livraison événementielle