Présentation des webhooks

Que sont les webhooks ?

Un webhook est un message automatiquement envoyé entre des applications lorsqu'un événement précis se produit. C'est un moyen idéal de connecter des applications et d'automatiser des processus. Avec Role.so, vous pouvez envoyer facilement les données des candidats, qu'ils aient manifesté leur intérêt ou décliné l'opportunité, vers toute plateforme prenant en charge les webhooks, notamment Make, Zapier et bien d'autres.

Cas d'utilisation et exemples

Vous pouvez automatiser et adapter votre processus à chaque scénario :

envoyer les coordonnées saisies par les candidats intéressés vers une feuille de calcul Google
envoyer automatiquement un SMS à un candidat qui a manifesté son intérêt pour un poste
envoyer une notification dans Slack lorsqu'un candidat manifeste son intérêt pour un poste ou le décline
enregistrer les données des candidats dans le système de suivi des candidatures de votre choix

Événements

Lors de la création d'un webhook, vous pouvez choisir entre deux types d'événements : Interested et Declined. Ces événements correspondent directement aux deux formulaires présents sur chaque pack candidat. Lorsqu'un formulaire est envoyé, nous transmettons un message à tous vos webhooks actifs correspondant au type d'événement.

Données

Selon le type d'événement (interested ou declined), nous envoyons une structure de données fixe. Vous pouvez utiliser ces données pour créer des automatisations dans vos applications et enrichir votre processus.

Données d'intérêt

{
  "contract_version": 1, // 📦 Version du contrat webhook
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Identifiant unique
  "action": "user_interested", // 🔔 Type d'action
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Date au format ISO
  "source": "web_form", // 🌐 Source de l'événement
  "source_url": "https://role.so/packs/demo", // 🔌 Lien vers le pack candidat où l'événement s'est produit
  "payload": {
    "role": "Software Engineer", // 💼 Rôle, tel que configuré dans le pack candidat
    "company": "Acme Inc", // 🏢 Entreprise, telle que configurée dans le pack candidat
    "user_details": {
      "name": "Jane Doe", // 👤 Champ de formulaire Nom
      "email": "hello@example.com", // ✉️ Champ de formulaire Email
      "phone": "07900000000", // 📞 Champ de formulaire Téléphone
      "website": "https://linkedin.com", // 🌐 Champ de formulaire URL du site web
      "attachments": [
        "https://role.so/mock_webhook_file_1.pdf",
        "https://role.so/mock_webhook_file_2.pdf"
      ], // 🔗 Liste des fichiers joints par les candidats
      "custom_answers": [
        {
          "label": "Availability",
          "value": "Immediately"
        }
      ] // 📝 Réponses facultatives aux questions personnalisées
    }
  }
}

Si aucune réponse à une question personnalisée n’est envoyée, la propriété custom_answers est omise du payload au lieu d’être définie à null. Les autres champs scalaires inutilisés ou désactivés sont indiqués par null, tandis que attachments est toujours un tableau et vaut [] lorsqu’aucun fichier n’est envoyé. Par exemple, si le formulaire d’intérêt de votre pack candidat contient uniquement les champs name et email, nous envoyons les données suivantes :

{
  // Les mêmes données que ci-dessus
  "payload": {
    "user_details": {
      "name": "Jane Doe",
      "email": "hello@example.com",
      "phone": null,
      "website": null,
      "attachments": []
    }
  }
}

Données de refus

Les données de refus ont une structure similaire à celle des données d'intérêt :

{
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Identifiant unique
  "action": "user_declined", // 🔔 Type d'action
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Date au format ISO
  "source": "web_form", // 🌐 Source de l'événement
  "source_url": "https://role.so/packs/demo", // 🔌 Lien vers le pack candidat où l'événement s'est produit
  "payload": {
    "role": "Software Engineer", // 💼 Rôle, tel que configuré dans le pack candidat
    "company": "Acme Inc", // 🏢 Entreprise, telle que configurée dans le pack candidat
    "decline_reasons": ["Salary", "Perks", "Office location"] // 📋 Liste des motifs de refus
  }
}

Si vous avez configuré des motifs de refus personnalisés dans votre formulaire, nous envoyons ces données à la place. Par exemple, si vos motifs de refus personnalisés sont Reason #1 et Reason #2, nous envoyons les données suivantes :

{
  // Les mêmes données que ci-dessus
  "payload": {
    "decline_reasons": ["Reason #1", "Reason #2"]
  }
}

Questions fréquentes

Q : Cette fonctionnalité est-elle disponible avec le forfait `Starter` ?

R : L’accès dépend des fonctionnalités incluses dans votre forfait actuel. Si votre compte dispose du droit d’utiliser les webhooks, vous pouvez utiliser cette fonctionnalité ; sinon, le tableau de bord affiche les options de mise à niveau disponibles.

Q : Combien de webhooks puis-je créer ?

R : Pour le moment, vous pouvez créer un maximum de 4 webhooks.

Q : Les événements et notifications sont-ils envoyés en temps réel ?

R : Dans la plupart des cas, oui. Toutefois, l'envoi des données vers votre application peut prendre entre 1 et 5 minutes.

Q : Puis-je envoyer des événements de test ?

R : Oui, une option permet d'envoyer des notifications de test afin de configurer facilement votre processus sans modifier les statistiques de vos packs candidat. Pour en savoir plus, consultez l'article d'aide Envoyer un événement de test.

Q : Comment les échecs sont-ils gérés ?

R : Les échecs réessayables, comme les erreurs réseau, les délais d'attente, les réponses HTTP 5xx et certaines réponses 4xx temporaires, font l'objet de 8 tentatives de livraison au total : la tentative initiale, puis jusqu'à 7 nouvelles tentatives. Les échecs définitifs, comme les payloads invalides, les endpoints bloqués par la politique de sécurité et les autres réponses 4xx, s'arrêtent après la première tentative. Un webhook peut être signalé comme défaillant après un seul échec de livraison et une livraison définitivement échouée peut être relancée manuellement. Pour en savoir plus, consultez l'article d'aide Surveiller les webhooks.

Q : Que se passe-t-il si un webhook échoue pendant une longue période ? Serai-je averti ?

R : Pas directement. Nous signalerons toutefois le webhook comme défaillant et un badge En échec apparaîtra sur celui-ci. Les échecs de livraison persistants ne désactivent pas automatiquement le webhook. Examinez l'endpoint et désactivez manuellement le webhook depuis la page des webhooks si nécessaire. Pour en savoir plus, consultez l'article d'aide Surveiller les webhooks.