Webhooks & Intégration API

Intégrez CSWeb avec vos applications tierces pour piloter le breakout, gérer les logs et automatiser vos workflows.

CSWeb Community Platform permet deux types d'intégration :

Webhooks entrants : CSPro → CSWeb (événements en temps réel)
API sortante : Application tierce → CSWeb (pilotage du breakout sélectif, logs, monitoring)

Cas d'Usage

1. Piloter le Breakout depuis une Application Tierce

Déclenchez le breakout sélectif d'un dictionnaire spécifique depuis votre dashboard ou application de monitoring.

Exemple : Application de supervision qui lance automatiquement le breakout du dictionnaire MENAGE quand 1000 nouveaux questionnaires sont détectés.

2. Centraliser les Logs dans un SIEM

Envoyez les logs CSWeb vers votre système de monitoring externe (ELK Stack, Splunk, Datadog).

Exemple : Alertes automatiques sur échecs de breakout ou erreurs de synchronisation.

3. Intégration BI/Dashboard

Récupérez les métriques de collecte en temps réel pour alimenter vos dashboards Power BI, Tableau ou Grafana.

Exemple : Dashboard affichant le nombre de questionnaires par région, taux de synchronisation, progression du breakout.

API pour Applications Tierces

Déclencher le Breakout Sélectif

Lancez le breakout d'un dictionnaire spécifique depuis votre application.

Endpoint : POST /api/breakout/trigger

curl -X POST http://localhost:8080/api/breakout/trigger \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dictionary": "MENAGE",
    "mode": "selective"
  }'

Réponse :

{
  "status": "success",
  "job_id": "breakout_123456",
  "dictionary": "MENAGE",
  "started_at": "2026-03-21T10:30:00Z"
}

Récupérer les Logs

Accédez aux logs de breakout depuis votre application de monitoring.

Endpoint : GET /api/logs/breakout

curl -X GET "http://localhost:8080/api/logs/breakout?dictionary=MENAGE&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Réponse :

{
  "logs": [
    {
      "timestamp": "2026-03-21T10:30:15Z",
      "level": "info",
      "dictionary": "MENAGE",
      "message": "Processing 1500 cases",
      "progress": "45%"
    }
  ]
}

Métriques en Temps Réel

Alimentez vos dashboards avec les métriques de collecte.

Endpoint : GET /api/metrics

curl -X GET http://localhost:8080/api/metrics \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Réponse :

{
  "total_cases": 15420,
  "cases_by_dictionary": {
    "MENAGE": 8200,
    "INDIVIDU": 7220
  },
  "breakout_status": {
    "MENAGE": "completed",
    "INDIVIDU": "in_progress"
  },
  "sync_rate": "98.5%"
}

Webhooks Entrants (CSPro → CSWeb)

Recevez des événements en temps réel depuis CSPro pour automatiser vos workflows.

1. Breakout Webhook

Fichier : breakout-webhook.php

Fonction : Lancer breakout automatiquement quand nouveau case uploadé.

Configuration CSPro :

Event: case_uploaded
URL: http://your-server/breakout-webhook.php

2. Log Reader Webhook

Fichier : log-reader-webhook.php

Fonction : Streamer logs CSPro vers système externe (ELK, Splunk).

3. Dictionary Schema Webhook

Fichier : dictionary-schema-webhook.php

Fonction : Synchroniser schemas dictionnaires vers base analytics.

Configuration

Token Sécurité

# .env
CSPRO_WEBHOOK_TOKEN=your_secret_token_here

CSWeb et CSPro doivent utiliser le même token.

CSPro Configuration

Dans CSPro :

Settings → Webhooks
Add Webhook :
- URL: http://your-server/breakout-webhook.php
- Token: your_secret_token_here
- Events: case_uploaded, case_modified

Tester Webhooks

Curl Test

curl -X POST http://localhost:8080/breakout-webhook.php \
  -H "X-Webhook-Token: your_secret_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "case_uploaded",
    "dictionary": "EVAL_DICT",
    "case_id": "abc123"
  }'

Response attendue :

{
  "status": "success",
  "message": "Breakout scheduled for EVAL_DICT"
}

Logs

# Voir logs webhook
tail -f /var/www/html/var/logs/webhook.log
 
# Filtrer événements
grep "case_uploaded" /var/www/html/var/logs/webhook.log

Événements

Événement	Description	Payload
`case_uploaded`	Nouveau questionnaire	`dictionary`, `case_id`
`case_modified`	Questionnaire modifié	`dictionary`, `case_id`, `changes`
`case_verified`	Questionnaire vérifié	`dictionary`, `case_id`
`dictionary_uploaded`	Nouveau dictionnaire	`dictionary`, `version`

Sécurité

Vérification Token

Tous les webhooks vérifient X-Webhook-Token :

<?php
$token = $_SERVER['HTTP_X_WEBHOOK_TOKEN'] ?? '';
$expected = getenv('CSPRO_WEBHOOK_TOKEN');
 
if (!hash_equals($expected, $token)) {
    http_response_code(401);
    exit(json_encode(['error' => 'Invalid token']));
}

HTTPS Recommandé

En production :

https://your-server.com/breakout-webhook.php

Customisation

Webhook Custom

Créer custom-webhook.php :

<?php
require_once __DIR__ . '/vendor/autoload.php';
 
// Vérifier token
$token = $_SERVER['HTTP_X_WEBHOOK_TOKEN'] ?? '';
if (!hash_equals(getenv('CSPRO_WEBHOOK_TOKEN'), $token)) {
    http_response_code(401);
    exit;
}
 
// Parser payload
$payload = json_decode(file_get_contents('php://input'), true);
 
// Logique custom
if ($payload['event'] === 'case_uploaded') {
    // Envoyer notification Slack
    $slack = 'https://hooks.slack.com/services/YOUR/WEBHOOK';
    $data = ['text' => "New case: {$payload['case_id']}"];
 
    $ch = curl_init($slack);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_exec($ch);
}
 
http_response_code(200);
echo json_encode(['status' => 'ok']);

Monitoring

Webhook Deliveries

Tracker succès/échecs :

CREATE TABLE webhook_deliveries (
    id SERIAL PRIMARY KEY,
    webhook_name VARCHAR(50),
    event VARCHAR(50),
    status VARCHAR(20),
    response_time INT,
    created_at TIMESTAMP DEFAULT NOW()
);

Metrics

-- Taux de succès
SELECT
    webhook_name,
    COUNT(*) as total,
    SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as success,
    AVG(response_time) as avg_response_ms
FROM webhook_deliveries
GROUP BY webhook_name;

Troubleshooting

Webhook Non Reçu

Vérifier :

# Firewall
curl http://your-server/breakout-webhook.php
 
# Logs Nginx/Apache
tail -f /var/log/nginx/access.log
 
# Logs CSPro (côté client)

Token Mismatch (401)

# Vérifier token CSWeb
echo $CSPRO_WEBHOOK_TOKEN
 
# Vérifier token CSPro
# (dans settings CSPro)

Timeout

Si webhook prend trop de temps :

// Répondre immédiatement
http_response_code(202);
echo json_encode(['status' => 'accepted']);
 
// Traitement async
fastcgi_finish_request();
exec("php process-breakout.php {$dictionary} > /dev/null 2>&1 &");

Ressources

Backup Automatique Monitoring