Webhooks Oplead - Documentation technique

Table des matières

1. Guide technique — API de gestion des abonnements
2. Structure du payload reçu
3. Sécurité — authentifier les webhooks
4. Limites & comportement

1. Guide technique — API de gestion des abonnements

Cette section s'adresse aux développeurs qui souhaitent gérer les webhooks via l'API Oplead.

Base URL : https://[votre-domaine].api.oplead.com/v1/Subscriptions

Authentification requise : Oui (clé API Oplead)

Créer un abonnement

POST /v1/Subscriptions
Content-Type: application/json
Authorization: Bearer {votre_token}

Body :

{
  "webhookName": "mon-webhook-qualification",
  "targetUrl": "https://mon-systeme.com/webhook/oplead",
  "eventTypes": [
    "lead.qualification_new",
    "lead.status_changed"
  ]
}

Réponse 200 :

{
  "name": "mon-webhook-qualification",
  "events": [
    { "name": "lead.qualification_new", "payloadUrl": "..." },
    { "name": "lead.status_changed", "payloadUrl": "..." }
  ],
  "targetUrl": "https://mon-systeme.com/webhook/oplead"
}

Lister les abonnements

GET /v1/Subscriptions
Authorization: Bearer {votre_token}

Réponse 200 : Tableau de tous les abonnements actifs (même format que la réponse de création).

Supprimer un abonnement

DELETE /v1/Subscriptions?webhookName=mon-webhook-qualification
Authorization: Bearer {votre_token}

2. Structure du payload reçu

Quand un événement se produit, Oplead envoie une requête POST vers votre URL avec le corps JSON suivant :

{
  "name": "mon-webhook-qualification",
  "secret": "votre-clé-secrète",
  "event": "lead.qualification_new",
  "data": {
    // Objet Lead complet avec toutes ses propriétés
  }
}

Contenu de data

L'objet data contient le lead complet au moment de l'événement, incluant :

• Identifiant et informations de contact (nom, prénom, téléphone, email…)
• Statut actuel et statut de qualification
• Commercial assigné
• Champs personnalisés
• Informations de rendez-vous
• Données de provenance (source, campagne…)

3. Sécurité — authentifier les webhooks

Chaque webhook est associé à une clé secrète unique, générée automatiquement par Oplead. Cette clé est transmise dans chaque payload sous le champ secret.

Comment l'utiliser :

Côté réception, avant de traiter le payload, vérifiez que la valeur du champ secret correspond bien à la clé configurée dans votre système :

# Exemple Python
def handle_webhook(payload):
    if payload["secret"] != MY_EXPECTED_SECRET:
        return 401  # Rejeter la requête
    # Traiter l'événement...

// Exemple Node.js
app.post('/webhook/oplead', (req, res) => {
  if (req.body.secret !== process.env.OPLEAD_WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }
  // Traiter l'événement...
});

⚠️ Ne jamais exposer votre clé secrète dans du code côté client ou dans un dépôt public. Stockez-la dans vos variables d'environnement.

Où récupérer la clé secrète : Dans Oplead, depuis Paramètres > Webhooks, cliquez sur Détails du webhook concerné, puis sur le bouton Copier la clé secrète.

4. Limites & comportement

Ce qu'il faut savoir

Pas de retry automatique : Si votre endpoint est temporairement indisponible au moment où Oplead envoie le webhook, la notification est perdue. Assurez-vous que votre URL de destination est fiable et disponible en permanence.

Timeout et erreurs : Oplead enregistre les tentatives d'envoi (succès et échecs) dans ses logs internes, mais ne renvoie pas automatiquement les webhooks en erreur.

Pour toute question technique, contactez l'équipe Oplead ou consultez la documentation API Oplead ici.

Si vous voulez savoir à quoi correspondent les webhooks Oplead, rdv ici.