Webhooks

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

Événements Disponibles

Événement	Déclencheur	Cas d'usage
content.pushed	Contenu envoyé via API	Synchronisation CRM, déclenchement de workflows
survey.created	Nouvelle source de données créée	Configuration auto dans outils externes
survey.published	Source de données publiée	Notifier l'équipe, démarrer le monitoring
series.created	Nouveau groupe de feedback créé	Initialiser les tableaux de bord

Payload du Webhook

JSON

{
  "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

En-tête	Valeur
X-Boundary-Signature	sha256={hmac_signature}
X-Boundary-Event	Type d'événement (ex: content.pushed)
Content-Type	application/json
User-Agent	BoundaryAI-Webhook/1.0

Vérification des Signatures

Vérifiez toujours la signature pour confirmer que le webhook provient bien de BoundaryAI :

Python

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

JavaScript

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 Réessai (Retry Policy)

Si votre endpoint échoue, nous réessayons avec un délai exponentiel (backoff) :

Tentative	Délai
1er réessai	1 minute
2ème réessai	5 minutes
3ème réessai	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

JSON

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

Codes d'Erreur

Erreurs d'Authentification (4xx)

Code	HTTP	Description	Solution
MISSING_AUTH	401	En-tête Authorization manquant	Ajoutez Authorization: Bearer {clé}
INVALID_AUTH_FORMAT	401	En-tête malformé	Utilisez le format Bearer {clé}
INVALID_TOKEN	401	La clé n'existe pas ou format incorrect	Vérifiez la clé, créez-en une nouvelle si nécessaire
REVOKED_KEY	401	La clé a été révoquée	Créez une nouvelle clé API

Erreurs de Permission (4xx)

Code	HTTP	Description	Solution
INSUFFICIENT_PERMISSION	403	La clé n'a pas la permission requise	Utilisez une clé avec la bonne permission
FORBIDDEN	403	La ressource appartient à une autre organisation	Vérifiez que les IDs sont corrects

Erreurs de Ressource (4xx)

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

Erreurs de Validation (4xx)

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

Erreurs de Quota & Débit (4xx)

Code	HTTP	Description	Solution
RATE_LIMITED	429	Trop de requêtes	Attendez les secondes indiquées dans Retry-After
INSUFFICIENT_APS	402	Pas assez de points d'analyse	Achetez plus d'APS ou utilisez une clé de test