Webhooks

Via la console d'administration

1. Connectez-vous à votre console d'administration Diamy et accédez à Paramètres > API > Webhooks
2. Cliquez sur Ajouter un webhook
3. Saisissez l'URL de destination qui recevra les notifications
4. Sélectionnez les événements que vous souhaitez recevoir
5. Configurez éventuellement un secret pour sécuriser vos webhooks
6. Cliquez sur Enregistrer

Via l'API

Vous pouvez également créer des webhooks programmatiquement via l'API :

curl -X POST "https://api.diamy.fr/v2/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-serveur.com/webhooks/diamy",
    "events": ["call.incoming", "call.ended", "voicemail.new"],
    "secret": "votre_secret_webhook",
    "description": "Webhook pour les événements d'appels"
  }'

Structure générale

{
  "id": "evt_123456789",
  "type": "call.incoming",
  "created_at": "2023-06-15T14:32:21Z",
  "data": {
    // Les données spécifiques à l'événement
  }
}

Chaque notification contient :

• id : Un identifiant unique pour l'événement
• type : Le type d'événement (ex: call.incoming)
• created_at : La date et l'heure à laquelle l'événement s'est produit (format ISO 8601)
• data : Un objet contenant les détails spécifiques à l'événement

Exemples par type d'événement

{
  "id": "evt_123456789",
  "type": "call.incoming",
  "created_at": "2023-06-15T14:32:21Z",
  "data": {
    "call": {
      "id": "call_123456",
      "direction": "inbound",
      "from": {
        "number": "+33123456789",
        "name": "Jean Dupont",
        "contact_id": "contact_789012"
      },
      "to": {
        "number": "+33987654321",
        "name": "Service Client",
        "user_id": "user_345678"
      },
      "status": "ringing",
      "timestamp": "2023-06-15T14:32:21Z",
      "queue": {
        "id": "queue_123",
        "name": "Support Technique"
      },
      "custom_data": {
        "crm_contact_id": "CRM-12345"
      }
    }
  }
}

En-tête de signature

Chaque requête webhook inclut un en-tête Diamy-Signature qui contient une signature HMAC-SHA256 du corps de la requête, générée avec votre secret webhook.

L'en-tête contient :

• t : Timestamp de la requête (en secondes depuis l'époque Unix)
• v1 : Signature HMAC-SHA256 du corps de la requête

Vérification de la signature

Pour vérifier la signature, vous devez :

1. Extraire le timestamp et la signature de l'en-tête
2. Vérifier que la requête n'est pas trop ancienne (pour éviter les attaques par rejeu)
3. Calculer le HMAC-SHA256 du corps de la requête avec votre secret webhook
4. Comparer la signature calculée avec celle reçue dans l'en-tête

const crypto = require('crypto');
const express = require('express');
const app = express();

app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

app.post('/webhooks/diamy', (req, res) => {
  const signature = req.headers['diamy-signature'];
  const webhookSecret = 'votre_secret_webhook';
  
  if (!signature) {
    return res.status(400).send('Signature manquante');
  }
  
  // Extraire le timestamp et la signature
  const [timestamp, receivedSignature] = signature.split(',').map(part => {
    const [key, value] = part.split('=');
    return value;
  });
  
  // Vérifier que la requête n'est pas trop ancienne (5 minutes max)
  const now = Math.floor(Date.now() / 1000);
  if (now - parseInt(timestamp) > 300) {
    return res.status(400).send('Requête expirée');
  }
  
  // Calculer la signature
  const hmac = crypto.createHmac('sha256', webhookSecret);
  hmac.update(req.rawBody);
  const expectedSignature = hmac.digest('hex');
  
  // Comparer les signatures
  if (receivedSignature !== expectedSignature) {
    return res.status(401).send('Signature invalide');
  }
  
  // Traiter l'événement
  const event = req.body;
  console.log('Événement reçu:', event.type);
  
  // Répondre avec un code 200 pour confirmer la réception
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Serveur webhook démarré sur le port 3000');
});

• Répondez rapidement : Votre endpoint doit répondre avec un code 200 dès que possible pour confirmer la réception. Traitez l'événement de manière asynchrone si nécessaire.
• Gérez les tentatives : Si votre endpoint ne répond pas avec un code 200, Diamy réessaiera d'envoyer l'événement plusieurs fois avec une stratégie de backoff exponentiel.
• Vérifiez les signatures : Utilisez toujours la vérification des signatures pour vous assurer que les requêtes proviennent bien de Diamy.
• Traitez les événements de manière idempotente : Un même événement peut être envoyé plusieurs fois en cas d'erreur. Assurez-vous que votre traitement est idempotent.
• Surveillez vos webhooks : Utilisez la console d'administration pour surveiller les livraisons de webhooks et les éventuelles erreurs.

Problèmes courants