Webhooks

Recevez des notifications en temps réel quand des événements se produisent.

Aperçu

Les webhooks vous permettent de :

• Obtenir des notifications d'événements instantanées
• Automatiser les workflows
• Synchroniser avec des systèmes externes
• Construire des intégrations réactives

Exigence de forfait

L'accès aux webhooks nécessite un forfait qui inclut les fonctionnalités API.

Comment fonctionnent les webhooks

1. Vous configurez une URL de point de terminaison
2. Sélectionnez les événements auxquels vous abonner
3. Quand des événements se produisent, nous envoyons des requêtes HTTP POST
4. Votre serveur traite le payload
5. Vous répondez avec un statut 2xx

Événements disponibles

Événement	Description
photo_request.created	Nouvelle demande de photos créée
photo_request.first_viewed	Demande consultée pour la première fois
photo_submission.created	Photos soumises (Liens permanents)
photo_request.submitted	Demande ponctuelle complétée
photo_request.expired	Demande expirée sans soumission
photo_submission.dropbox_synced	Photo synchronisée sur Dropbox avec lien partagé

Créer un webhook

Étapes

1. Allez dans Webhooks dans la barre latérale
2. Cliquez sur Créer un webhook
3. Entrez un nom descriptif
4. Fournissez l'URL de votre point de terminaison
5. Sélectionnez les événements auxquels vous abonner
6. Basculez Actif (par défaut : activé)
7. Cliquez sur Créer

Exigences du point de terminaison

Exigence	Valeur
Protocole	HTTPS requis
Accessibilité	Internet public
Réponse	Code de statut 2xx
Timeout	30 secondes max

Réseaux privés

Les adresses de réseaux privés et internes (localhost, 10.x.x.x, 192.168.x.x) ne sont pas autorisées.

Payload du webhook

Format de la requête

POST /votre-endpoint HTTP/1.1
Host: votre-serveur.com
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: wh_123456
X-Webhook-Timestamp: 1609459200

Structure du payload

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Envoyez des photos du véhicule",
    "photos": [
      {
        "id": "photo_xyz789",
        "url": "https://...",
        "slot_instructions": "Vue de face",
        "metadata": {
          "gps_lat": 45.1234,
          "gps_lng": 12.5678,
          "captured_at": "2024-01-15T10:28:00Z"
        }
      }
    ],
    "submitted_at": "2024-01-15T10:30:00Z"
  }
}

Vérification de signature

Pourquoi vérifier

Vérifiez les signatures des webhooks pour s'assurer que :

• La requête vient de Visiono
• Le payload n'a pas été altéré
• Prévenir les attaques par rejeu

En-tête de signature

X-Webhook-Signature: sha256=abc123def456...

Étapes de vérification

// Exemple PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'votre-secret-webhook';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Signature invalide');
}

// Exemple Node.js
const crypto = require('crypto');

const payload = JSON.stringify(req.body);
const signature = req.headers['x-webhook-signature'];
const secret = process.env.WEBHOOK_SECRET;

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).send('Signature invalide');
}

Gérer les webhooks

Tester un webhook

Envoyer un événement de test :

1. Cliquez sur Tester sur le webhook
2. Confirmez l'action
3. Vérifiez le statut de la réponse
4. Consultez les logs en cas d'échec

Voir les logs

Consultez l'historique de livraison :

1. Cliquez sur Logs sur le webhook
2. Consultez les livraisons récentes
3. Vérifiez le statut et la réponse
4. Déboguez les échecs

Détails des logs

Chaque log affiche :

• Type d'événement
• Horodatage
• Statut de la réponse
• Temps de réponse
• Corps de la requête/réponse (pour le débogage)

Régénérer le secret

Obtenir un nouveau secret de signature :

1. Cliquez sur Régénérer le secret
2. Confirmez l'action
3. Copiez le nouveau secret immédiatement
4. Mettez à jour votre serveur

Mettez à jour le serveur d'abord

Après régénération, l'ancien secret cesse de fonctionner. Mettez à jour votre code de vérification avant de régénérer.

Désactiver un webhook

Arrêter temporairement de recevoir des événements :

1. Cliquez sur Désactiver
2. Confirmez l'action
3. Les événements ne sont plus envoyés
4. Réactivez quand prêt

Supprimer un webhook

Supprimer définitivement :

1. Cliquez sur Supprimer
2. Confirmez l'action
3. Tous les logs sont supprimés

Politique de réessai

Réessais automatiques

Les livraisons échouées sont réessayées :

Tentative	Délai
1	Immédiat
2	1 minute
3	5 minutes
4	30 minutes
5	2 heures

Critères d'échec

Une livraison échoue si :

• Timeout de connexion (30s)
• Réponse non-2xx
• Erreur réseau
• Erreur SSL

Après les réessais max

Si tous les réessais échouent :

• L'événement est marqué comme échoué
• Enregistré pour examen
• Pas de tentatives supplémentaires

Bonnes pratiques

Conception du point de terminaison

• Répondez rapidement (< 5 secondes)
• Traitez de manière asynchrone si nécessaire
• Retournez 2xx immédiatement
• Gérez l'idempotence

Gestion des erreurs

// Modèle recommandé
app.post('/webhook', async (req, res) => {
  // Vérifier la signature d'abord
  if (!verifySignature(req)) {
    return res.status(401).send('Invalide');
  }

  // Acquitter immédiatement
  res.status(200).send('OK');

  // Traiter de manière asynchrone
  processWebhookAsync(req.body);
});

Idempotence

Les événements peuvent être envoyés plus d'une fois. Gérez les doublons :

// Vérifier si déjà traité
const eventId = req.headers['x-webhook-id'];
if (await isProcessed(eventId)) {
  return res.status(200).send('Déjà traité');
}

// Traiter et marquer comme géré
await processEvent(req.body);
await markProcessed(eventId);

Surveillance

• Enregistrez tous les webhooks entrants
• Alertez sur les échecs
• Surveillez les temps de réponse
• Suivez les volumes d'événements

Dépannage

Ne reçoit pas d'événements

1. Vérifiez que le webhook est actif
2. Vérifiez que l'URL du point de terminaison est correcte
3. Assurez-vous que HTTPS fonctionne
4. Vérifiez que le serveur est accessible
5. Vérifiez les événements sélectionnés

Discordance de signature

1. Utilisez le bon secret
2. Comparez le payload complet (pas parsé)
3. Vérifiez les problèmes d'encodage
4. Vérifiez l'algorithme HMAC (SHA256)

Timeouts

1. Réduisez le temps de traitement
2. Acquittez immédiatement
3. Traitez de manière asynchrone
4. Vérifiez les ressources du serveur

Voir les livraisons échouées

1. Allez dans les logs du webhook
2. Filtrez par statut (échoué)
3. Consultez les détails de la requête/réponse
4. Corrigez et retestez

Limites des webhooks

Par forfait

Forfait	Webhooks max
Professionnel	5 webhooks
Entreprise	Illimité

Limites de débit

Limite	Valeur
Événements par minute	100
Taille du payload	1 Mo

Pages connexes

• Clés API - Authentification API
• Référence API - Documentation API complète
• Intégrations - Intégrations pré-construites