API des webhooks

API des webhooks #

Configurez des webhooks pour recevoir des notifications en temps réel lorsque des événements se produisent dans votre compte VoxPria.

Créer un webhook #

Point de terminaison : POST /api/v1/webhooks

curl -X POST "https://app.voxpria.com/api/v1/webhooks" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "url": "https://yourapp.com/webhooks/voxpria",
    "events": [
      "call.completed",
      "campaign.finished"
    ],
    "active": true
  }'

Réponse #

{
  "success": true,
  "data": {
    "webhookId": "webhook_abc123",
    "url": "https://yourapp.com/webhooks/voxpria",
    "events": ["call.completed", "campaign.finished"],
    "secret": "whsec_xyz789...",
    "active": true
  }
}

Lister les webhooks #

Point de terminaison : GET /api/v1/webhooks

curl -X GET "https://app.voxpria.com/api/v1/webhooks" 
  -H "Authorization: Bearer YOUR_API_KEY"

Événements disponibles #

Charge utile du webhook #

Exemple de charge utile call.completed :

{
  "event": "call.completed",
  "timestamp": "2025-02-09T12:00:00Z",
  "data": {
    "callId": "call_xyz789",
    "status": "completed",
    "duration": 127,
    "toNumber": "+14155551234",
    "recording": "https://...",
    "transcript": "..."
  }
}

Vérifier les signatures des webhooks #

Vérifiez que les webhooks proviennent bien de VoxPria à l’aide de la signature :

Node.js #

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return `sha256=${hmac}` === signature;
}

// In your webhook handler
app.post('/webhooks/voxpria', (req, res) => {
  const signature = req.headers['x-voxpria-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  console.log('Event:', req.body.event);
  res.status(200).send('OK');
});

Python #

import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret):
    computed = hmac.new(
        secret.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    
    return f"sha256={computed}" == signature

# In your webhook handler
@app.route('/webhooks/voxpria', methods=['POST'])
def webhook_handler():
    signature = request.headers.get('X-Voxpria-Signature')
    
    if not verify_webhook_signature(
        request.json,
        signature,
        os.getenv('WEBHOOK_SECRET')
    ):
        return 'Invalid signature', 401
    
    # Process webhook
    print('Event:', request.json['event'])
    return 'OK', 200

Meilleures pratiques #

• ✅ Vérifiez toujours les signatures des webhooks
• ✅ Répondez rapidement avec un statut 200
• ✅ Traitez les webhooks de façon asynchrone
• ✅ Mettez en place l’idempotence (les webhooks peuvent être envoyés plusieurs fois)
• ✅ Utilisez uniquement des URL HTTPS
• ✅ Gérez les nouvelles tentatives de webhook avec grâce