API WhatsApp et les webhooks : guide pour les logiciels RH

Un webhook WhatsApp API est une URL HTTPS de votre serveur vers laquelle Meta envoie une requête HTTP POST dès qu'un événement se produit sur votre compte : message reçu, statut de livraison mis à jour, statut de lecture, réponse à un bouton. Pour un logiciel RH, c'est le mécanisme qui permet de réagir immédiatement quand un candidat répond à une convocation d'entretien ou quand un collaborateur confirme sa participation à une formation — sans polling ni intervention manuelle.

Les types d'événements WhatsApp envoyés par webhook

Meta regroupe les événements dans une structure JSON sous le champ entry[].changes[].value. Les événements les plus importants pour un logiciel RH :

Messages entrants (messages)

• Texte libre d'un candidat ou collaborateur.
• Réponse à un bouton interactif (par exemple "Confirmer" ou "Reporter").
• Réponse à une liste déroulante (sélection d'un créneau horaire).
• Image ou document partagé (CV, justificatif, photo de carte d'identité).

Statuts de messages (statuses)

• sent : le message a quitté les serveurs Meta.
• delivered : le message est arrivé sur l'appareil du destinataire.
• read : le destinataire a ouvert la conversation.
• failed : échec de livraison (numéro invalide, opt-out, etc.).

Événements système

• Changement de qualité du numéro (phone_number_quality_update).
• Changement de statut de template (message_template_status_update).

Pour un logiciel RH, les événements les plus utiles sont les messages entrants (réponses des collaborateurs) et les statuts read et failed (pour détecter les non-réceptions et relancer si nécessaire).

Configuration technique d'un endpoint webhook

Votre endpoint doit répondre à deux types de requêtes Meta :

1. La vérification initiale (GET) Quand vous enregistrez votre webhook dans le Meta Business Manager, Meta envoie une requête GET avec trois paramètres : hub.mode, hub.verify_token (un token que vous avez défini), et hub.challenge. Votre endpoint doit vérifier le token et retourner la valeur de hub.challenge. C'est un handshake de sécurité à sens unique.

2. Les événements temps réel (POST) Meta envoie des requêtes POST avec un corps JSON pour chaque événement. Votre endpoint doit :

• Retourner un HTTP 200 OK immédiatement, avant tout traitement.
• Traiter l'événement de façon asynchrone (queue de traitement, worker en arrière-plan).
• Valider la signature X-Hub-Signature-256 de chaque requête pour garantir qu'elle provient bien de Meta.

Si votre endpoint ne répond pas en moins de 20 secondes ou retourne un code d'erreur, Meta retentera l'envoi selon une politique de retry exponentielle. Les événements non acquittés sont perdus après un certain délai.

Bonne pratique	Raison
Retourner 200 immédiatement	Éviter les retries et les pertes d'événements
Valider X-Hub-Signature-256	Sécurité contre les requêtes falsifiées
Traitement asynchrone	Pas de timeout sur les opérations longues
Idempotence des handlers	Meta peut envoyer le même événement deux fois
Logs structurés par événement	Débogage et audit facilités

Cas d'usage RH avec webhooks

Confirmation automatique d'entretien Votre logiciel envoie un message template avec deux boutons : "Confirmer" et "Annuler". Quand le candidat appuie sur "Confirmer", votre webhook reçoit l'événement de réponse au bouton, met à jour le statut RDV dans votre base, et envoie automatiquement une confirmation avec l'adresse et le lien Google Maps.

Gestion des présences à une formation La veille d'une session de formation, votre logiciel envoie un rappel à chaque participant avec un bouton "Je serai présent". Le webhook capture les réponses en temps réel. À 8h le jour J, votre formateur reçoit la liste définitive des présences confirmées.

Collecte de documents Vous demandez à un nouveau collaborateur de vous envoyer une photo de sa pièce d'identité par WhatsApp. Votre webhook reçoit le message de type image, télécharge le fichier depuis l'URL Media de Meta (valide 5 minutes), et l'attache au dossier RH dans votre SIRH.

Alertes de non-réception Si le statut d'un message critique passe en failed (numéro invalide ou bloqé), votre webhook peut déclencher une alerte RH pour qu'un gestionnaire recontacte le collaborateur par email ou téléphone.

Pour les détails sur les templates utilisés dans ces flux, notre article sur les templates WhatsApp et leurs catégories vous guidera sur les bons types à utiliser selon chaque cas RH.

Intégration avec Whakup

Whakup expose un endpoint webhook centralisé qui normalise le format des événements Meta. Au lieu de gérer la complexité du payload JSON brut de Meta, vous recevez des événements structurés et documentés. Whakup gère aussi le retry et la déduplication des événements, ce qui vous évite de traiter deux fois la même confirmation de présence.

L'hébergement est en Union Européenne, ce qui est un prérequis pour tout logiciel RH traitant des données de salariés sous RGPD. Découvrez l'API WhatsApp Whakup et connectez votre SIRH à WhatsApp en quelques heures.

Pour une vue d'ensemble de l'API avant de démarrer l'intégration, consultez notre guide complet de l'API WhatsApp Business.

FAQ

Peut-on avoir plusieurs URLs webhook pour le même numéro ?

Non. Meta ne supporte qu'une seule URL webhook par app Meta (qui couvre tous les numéros rattachés à cette app). Si vous devez router des événements vers plusieurs systèmes, vous devez implémenter un dispatcher côté serveur qui reçoit tous les événements et les distribue aux bons handlers.

Comment tester un webhook en développement sans serveur public ?

Utilisez ngrok ou un équivalent (localtunnel, cloudflared) pour exposer votre serveur local en HTTPS public. Meta exige HTTPS pour les webhooks. Alternativement, utilisez le sandbox WhatsApp de test disponible dans le Meta Business Manager pour simuler des messages entrants sans vrais destinataires.

Les webhooks sont-ils fiables pour des événements critiques (confirmation d'entretien) ?

Ils sont fiables mais pas garantis à 100 %. Meta peut retarder des événements en cas de forte charge. Pour les flux critiques, complétez votre logique webhook avec un polling périodique sur l'API de statut des messages, et implémentez des alertes sur les messages sans statut read après 24h.

Faut-il une infrastructure spéciale pour gérer un grand volume de webhooks ?

Pour quelques centaines d'événements par jour, un serveur standard suffit. Au-delà de quelques milliers par heure (logiciel RH multi-clients, forte adoption), privilégiez une queue de messages (Redis, SQS, RabbitMQ) devant votre endpoint pour absorber les pics et garantir le traitement.

---

Les webhooks sont le système nerveux de votre intégration WhatsApp RH. Sans eux, vous avez un canal d'envoi mais pas de réception structurée. Avec eux, vous construisez des workflows RH entièrement automatisés. Whakup fournit les webhooks, la documentation et le support technique pour intégrer WhatsApp dans votre logiciel RH sans partir de zéro. Commencez avec l'API Whakup.