Webhooks

Recevez des notifications HTTP en temps réel lorsque des événements se produisent dans BoundaryAI.

Aperçu

Les webhooks vous permettent de recevoir des notifications en temps réel lorsque des événements se produisent dans BoundaryAI. Au lieu d'interroger notre API, votre serveur reçoit automatiquement des requêtes HTTP POST.

Cas d'utilisation :

• Synchroniser le contenu poussé vers votre entrepôt de données

• Déclencher des flux de travail lorsque des enquêtes sont créées/publiées

• Construire des tableaux de bord en temps réel

• S'intégrer à Slack, Teams ou d'autres outils

Prérequis

1. Accès administrateur - Seuls les administrateurs de l'organisation peuvent gérer les webhooks

2. Point de terminaison HTTPS - L'URL de votre webhook doit utiliser HTTPS (HTTP non autorisé)

3. URL publique - L'URL doit être accessible publiquement (pas de localhost, d'adresses IP privées ou de domaines internes)

4. Temps de réponse - Votre point de terminaison doit répondre en moins de 10 secondes

Événements disponibles

Événement	Description	Quand il se déclenche
content.pushed	Le contenu a été poussé via l'API	Après réussite de /api/input/content/push ou /api/input/content/push/bulk
survey.created	Une nouvelle enquête a été créée	Après réussite de /api/input/survey/create
survey.published	Une enquête a été publiée	Après réussite de /api/input/survey/publish
series.created	Un nouveau groupe de feedback a été créé	Après réussite de /api/input/survey_series/create

Payload du webhook

{
  "event": "content.pushed",
  "timestamp": "2025-01-15T10:30:00.000000Z",
  "data": {
    "survey_series_id": 123,
    "survey_id": 456,
    "question_id": 789,
    "lines_pushed": 50,
    "api_key_id": 1
  }
}

En-têtes HTTP

Chaque requête de webhook inclut ces en-têtes :

En-tête	Description	Exemple
X-Boundary-Signature	Signature HMAC-SHA256 pour vérification	sha256=abc123...
X-Boundary-Event	Le type d'événement qui a déclenché ce webhook	content.pushed
Content-Type	Toujours JSON	application/json
User-Agent	Identifie BoundaryAI comme l'expéditeur	BoundaryAI-Webhook/1.0

Gestion des webhooks

Tous les points de terminaison de gestion des webhooks nécessitent une authentification JWT (pas de clé API).

Lister les webhooks

GET /api/webhooks
Authorization: Bearer {JWT_TOKEN}

^Réponse

{
  "is_admin": true,
  "webhooks": [
    {
      "id": 1,
      "name": "Mon Webhook",
      "url": "https://example.com/webhook",
      "events": ["content.pushed", "survey.created"],
      "is_active": true,
      "failure_count": 0,
      "created_at": "2025-01-15T10:00:00+00:00",
      "last_triggered_at": null
    }
  ],
  "available_events": ["content.pushed", "survey.created", "survey.published", "series.created"]
}

Créer un webhook

POST /api/webhooks
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "Mon Webhook",
  "url": "https://example.com/webhook",
  "events": ["content.pushed", "survey.created"]
}

^Réponse

{
  "webhook": {
    "id": 1,
    "name": "Mon Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed", "survey.created"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  },
  "secret": "ngQCfdLY0Ykp0_OLrXlMhzPfYNo0WV1w9j4Imt1ddMM",
  "message": "Enregistrez le secret maintenant ! Vous ne pourrez plus le voir par la suite."
}

⚠️ Important : Enregistrez le secret immédiatement - il n'est affiché qu'une seule fois !

Mettre à jour un webhook

PATCH /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "Nom mis à jour",
  "events": ["content.pushed"],
  "is_active": true
}

^Réponse

{
  "webhook": {
    "id": 1,
    "name": "Nom mis à jour",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  }
}

Webhook unique

GET /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Réponse

{
  "webhook": {
    "id": 1,
    "name": "Mon Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": "2025-01-15T12:00:00+00:00"
  }
}

Supprimer un webhook

DELETE /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Réponse

{
  "message": "Webhook supprimé avec succès",
  "webhook_id": 1
}

Vérification des signatures

Toujours vérifier la signature pour confirmer que le webhook provient de BoundaryAI :

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# Utilisation dans Flask :
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Boundary-Signature')
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.headers.get('X-Boundary-Event')
    data = request.json
    # Traiter le webhook...
    return 'OK', 200

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

// Utilisation dans Express :
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-boundary-signature'];
  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.headers['x-boundary-event'];
  const data = JSON.parse(req.body);
  // Traiter le webhook...
  res.status(200).send('OK');
});

Politique de nouvelle tentative

Si votre point de terminaison échoue, nous réessayons avec un backoff exponentiel :

Tentative	Délai
1re nouvelle tentative	1 minute
2e nouvelle tentative	5 minutes
3e nouvelle tentative	15 minutes

Après 10 échecs consécutifs, le webhook est automatiquement désactivé.

---

Référence des erreurs

Format de réponse d'erreur

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Description lisible par un humain",
    "details": { }
  }
}

Codes d'erreur

Erreurs d'authentification (4xx)

Code	HTTP	Description	Solution
MISSING_AUTH	401	Pas d'en-tête Authorization	Ajouter Authorization: Bearer {key}
INVALID_AUTH_FORMAT	401	En-tête mal formé	Utilisez Bearer {key} format
INVALID_TOKEN	401	La clé n'existe pas ou format incorrect	Vérifier la clé, en créer une nouvelle si nécessaire
REVOKED_KEY	401	La clé a été révoquée	Créer une nouvelle clé API

Erreurs d'autorisation (4xx)

Code	HTTP	Description	Solution
INSUFFICIENT_PERMISSION	403	La clé n'a pas la permission requise	Utiliser une clé avec la permission correcte
FORBIDDEN	403	La ressource appartient à une autre organisation	Vérifier que les ID sont corrects

Erreurs de ressource (4xx)

Code	HTTP	Description	Solution
SURVEY_SERIES_NOT_FOUND	404	Le groupe de feedback n'existe pas	Vérifier survey_series_id
SURVEY_NOT_FOUND	404	La source de données n'existe pas	Vérifier survey_id
QUESTION_NOT_FOUND	404	La question n'existe pas	Vérifier question_id

Erreurs de validation (4xx)

Code	HTTP	Description	Solution
VALIDATION_ERROR	400	Données de requête invalides	Vérifier details pour les champs spécifiques
INVALID_QUESTION_TYPE	400	Pousser du texte vers une question non textuelle	Utiliser une question avec accepts_text: true

Erreurs de taux et de quota (4xx)

Code	HTTP	Description	Solution
RATE_LIMITED	429	Trop de requêtes	Attendre Retry-After secondes
INSUFFICIENT_APS	402	Pas assez de points d'analyse	Acheter plus d'APS ou utiliser clé de test