Webhooks

Les webhooks permettent a Reepli d'envoyer des notifications en temps reel a vos systemes externes lorsque des evenements se produisent, et de recevoir des donnees depuis des sources externes pour declencher des actions dans Reepli.

Qu'est-ce qu'un webhook ?

Un webhook est un mecanisme de communication HTTP qui permet a une application d'envoyer automatiquement des donnees a une URL lorsqu'un evenement specifique se produit. Contrairement au polling (interrogation periodique), les webhooks transmettent les donnees instantanement.

Methode	Fonctionnement	Latence	Charge serveur
Polling (API)	Votre serveur interroge Reepli periodiquement	Elevee (secondes a minutes)	Elevee
Webhooks	Reepli notifie votre serveur instantanement	Faible (millisecondes)	Faible

Pre-requis

• Un compte Reepli.ai avec un plan Business ou Enterprise. Voir Plans et tarifs.
• Un serveur web accessible depuis Internet capable de recevoir des requetes HTTP POST.
• Les droits Administrateur sur votre compte Reepli. Voir Roles et permissions.
• Des connaissances techniques de base (HTTP, JSON).

Webhooks sortants (Reepli vers votre systeme)

Evenements disponibles

Evenement	Identifiant	Description
Message recu	message.received	Un nouveau message entrant est recu
Message envoye	message.sent	Un message sortant est envoye
Message delivre	message.delivered	Un message a ete delivre
Message lu	message.read	Un message a ete lu
Contact cree	contact.created	Un nouveau contact est cree
Contact mis a jour	contact.updated	Un contact est modifie
Conversation ouverte	conversation.opened	Une nouvelle conversation debute
Conversation fermee	conversation.closed	Une conversation est cloturee
Agent assigne	conversation.assigned	Un agent est assigne a une conversation
Formulaire soumis	form.submitted	Un formulaire chatbot est complete
Campagne envoyee	campaign.sent	Une campagne de diffusion est lancee
Campagne terminee	campaign.completed	Une campagne est terminee

Configurer un webhook sortant

1. Accedez a Parametres > Integrations > Webhooks.
2. Cliquez sur Ajouter un webhook.
3. Remplissez les champs :
   • Nom : un nom descriptif (ex : "Notifications CRM").
   • URL de destination : l'URL de votre endpoint (ex : https://mon-serveur.com/webhooks/reepli).
   • Evenements : selectionnez les evenements a ecouter.
   • Statut : Actif ou Inactif.
4. Configurez l'authentification (voir section suivante).
5. Cliquez sur Enregistrer.
6. Cliquez sur Tester pour envoyer un payload de test.

Format du payload

Chaque notification webhook est envoyee sous forme de requete HTTP POST avec un corps JSON. Voici la structure generale :

{
  "event": "message.received",
  "timestamp": "2026-04-03T10:30:00Z",
  "account_id": "acc_123456",
  "data": {
    "id": "msg_789012",
    "contact": {
      "id": "cnt_345678",
      "name": "Marie Dupont",
      "phone": "+33612345678"
    },
    "conversation_id": "conv_901234",
    "content": {
      "type": "text",
      "body": "Bonjour, je souhaite suivre ma commande."
    },
    "metadata": {
      "source": "whatsapp",
      "agent_id": null,
      "tags": ["client", "support"]
    }
  }
}

Exemples de payloads par evenement

Contact cree

{
  "event": "contact.created",
  "timestamp": "2026-04-03T14:00:00Z",
  "account_id": "acc_123456",
  "data": {
    "id": "cnt_567890",
    "name": "Jean Martin",
    "phone": "+33698765432",
    "email": "[email protected]",
    "tags": ["nouveau"],
    "custom_fields": {},
    "created_at": "2026-04-03T14:00:00Z"
  }
}

Conversation fermee

{
  "event": "conversation.closed",
  "timestamp": "2026-04-03T16:30:00Z",
  "account_id": "acc_123456",
  "data": {
    "id": "conv_112233",
    "contact_id": "cnt_345678",
    "agent_id": "agt_445566",
    "duration_seconds": 1245,
    "messages_count": 12,
    "resolution": "resolved",
    "tags": ["support", "facturation"],
    "closed_at": "2026-04-03T16:30:00Z"
  }
}

Authentification des webhooks

Signature HMAC-SHA256

Chaque requete webhook inclut un en-tete de signature pour verifier son authenticite :

X-Reepli-Signature: sha256=a1b2c3d4e5f6...

Pour verifier la signature cote serveur :

1. Recuperez votre secret de webhook dans les parametres du webhook.
2. Calculez le HMAC-SHA256 du corps de la requete avec votre secret.
3. Comparez le resultat avec la valeur de l'en-tete X-Reepli-Signature.

Exemple en Python :

import hmac
import hashlib

def verify_signature(payload_body, signature_header, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Exemple en Node.js :

const crypto = require('crypto');

function verifySignature(payloadBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payloadBody)
    .digest('hex');
  return signatureHeader === `sha256=${expected}`;
}

Securite

Verifiez toujours la signature des webhooks entrants. Sans cette verification, votre endpoint est vulnerable aux requetes malveillantes. Ne traitez jamais un webhook dont la signature est invalide.

Authentification par en-tete

Vous pouvez egalement configurer un en-tete d'authentification personnalise :

1. Dans la configuration du webhook, activez Authentification par en-tete.
2. Saisissez le nom de l'en-tete (ex : X-API-Key).
3. Saisissez la valeur (ex : votre cle API).

Cet en-tete sera inclus dans chaque requete webhook.

Webhooks entrants (Votre systeme vers Reepli)

Les webhooks entrants permettent a vos systemes d'envoyer des donnees a Reepli pour declencher des actions.

Creer un webhook entrant

1. Accedez a Parametres > Integrations > Webhooks > Entrants.
2. Cliquez sur Creer un webhook entrant.
3. Donnez un nom au webhook.
4. Selectionnez l'action a declencher :
   • Creer un contact
   • Envoyer un message
   • Ajouter une etiquette
   • Demarrer un flux chatbot
5. Copiez l'URL du webhook generee.
6. Configurez le mapping des champs.

URL generee

L'URL generee a la forme suivante :

https://api.reepli.ai/webhooks/incoming/wh_abcdef123456

Envoyer des donnees au webhook

Envoyez une requete HTTP POST a l'URL avec un corps JSON :

{
  "phone": "+33612345678",
  "name": "Marie Dupont",
  "email": "[email protected]",
  "tags": ["lead", "site-web"],
  "custom_fields": {
    "source": "formulaire-contact",
    "produit_interesse": "Plan Pro"
  }
}

Gestion des echecs et retentatives

Politique de retentative

Lorsqu'un webhook echoue (code HTTP 4xx ou 5xx, timeout, erreur reseau), Reepli applique la politique de retentative suivante :

Tentative	Delai	Description
1ere	Immediat	Premiere tentative
2eme	30 secondes	Premiere retentative
3eme	2 minutes	Deuxieme retentative
4eme	10 minutes	Troisieme retentative
5eme	1 heure	Quatrieme retentative
6eme	4 heures	Cinquieme retentative (derniere)

Codes de reponse attendus

Votre serveur doit repondre avec un code HTTP dans les 30 secondes :

Code	Signification	Action Reepli
200, 201, 202	Succes	Webhook marque comme delivre
3xx	Redirection	Suivie une fois, puis echec
4xx	Erreur client	Pas de retentative (sauf 429)
429	Trop de requetes	Retentative avec backoff
5xx	Erreur serveur	Retentative selon la politique
Timeout	Pas de reponse en 30s	Retentative selon la politique

Timeout

Votre endpoint doit repondre en moins de 30 secondes. Si le traitement est long, acceptez le webhook (code 200) et traitez les donnees de maniere asynchrone.

Desactivation automatique

Un webhook est automatiquement desactive apres 50 echecs consecutifs. Vous recevrez une notification par e-mail. Pour le reactiver :

1. Accedez a Parametres > Integrations > Webhooks.
2. Identifiez le webhook desactive (icone d'avertissement).
3. Corrigez le probleme sur votre serveur.
4. Cliquez sur Reactiver.
5. Testez avec le bouton Tester.

Journaux et monitoring

Consulter les journaux

1. Accedez a Parametres > Integrations > Webhooks.
2. Selectionnez le webhook concerne.
3. Cliquez sur l'onglet Journaux.
4. Consultez l'historique des livraisons avec :
   • Horodatage
   • Evenement
   • Code de reponse
   • Temps de reponse
   • Payload envoye
   • Reponse recue

Renvoyer un webhook

Si un webhook a echoue, vous pouvez le renvoyer manuellement :

1. Dans les journaux, identifiez le webhook echoue.
2. Cliquez sur Renvoyer.
3. Le webhook sera redelivre avec le payload original.

Limites

Parametre	Business	Enterprise
Webhooks sortants actifs	10	50
Webhooks entrants actifs	5	25
Requetes par minute	60	200
Retention des journaux	7 jours	30 jours
Taille max du payload	5 Mo	10 Mo

Depannage

Le webhook ne recoit rien

• Verifiez que le webhook est actif dans les parametres.
• Assurez-vous que votre serveur est accessible depuis Internet.
• Verifiez les regles de pare-feu et les listes blanches IP.
• Testez avec un service comme webhook.site pour verifier que Reepli envoie bien les requetes.

Signature invalide

• Assurez-vous d'utiliser le bon secret de webhook.
• Verifiez que vous comparez le corps brut de la requete (pas le JSON parse).
• Verifiez l'encodage des caracteres (UTF-8).

Pour d'autres problemes, consultez la page de depannage ou contactez le support.

Ressources complementaires

• Vue d'ensemble des integrations
• API REST Reepli
• Automatiser avec Zapier
• Creer des scenarios avec Make