Un webhook est une adresse sur votre serveur (ou dans Zapier, Make ou n8n) que PALMS appelle dès que quelque chose se produit : un client écrit, un message est distribué, une conversation est fermée, un contact reçoit une étiquette. Votre système n’a plus besoin de demander sans cesse des nouvelles à PALMS.
Seuls les Propriétaires et Administrateurs peuvent configurer les webhooks, dans Intégrations → Webhooks.
Vue d’ensemble
- Vous donnez à PALMS une adresse https:// et choisissez les événements voulus.
- Quand l’un d’eux se produit, PALMS envoie une requête
POSTavec un corps JSON qui le décrit. - Votre serveur répond avec un statut 2xx (200, 201, 204…) en moins de 10 secondes pour dire « reçu ».
- Sinon, PALMS réessaie plus tard (voir Nouvelles tentatives).
Chaque appel est signé avec un secret que vous seuls et PALMS connaissez : votre serveur peut vérifier qu’il vient bien de PALMS.
Ajouter un webhook
- Ouvrez Intégrations → Webhooks et cliquez sur Add webhook.
- Saisissez l’adresse, par exemple
https://example.com/palms/webhook. Elle doit commencer parhttps://et être joignable depuis Internet. Les adresses d’un réseau privé (192.168…,10…,localhost) sont refusées. - Choisissez les événements. Commencez par le strict nécessaire ; vous pourrez les modifier.
- Copiez le secret de signature et placez-le dans la configuration de votre serveur.
- Cliquez sur Send test. PALMS envoie un événement
ping; si votre serveur répond 2xx, vous verrez « It works ».
Pas de serveur ? Dans Zapier, utilisez « Webhooks by Zapier → Catch Hook », dans Make « Webhooks → Custom webhook », dans n8n le nœud « Webhook ». Collez l’adresse qu’ils vous donnent.
Jusqu’à 10 webhooks par organisation. Une même adresse peut recevoir plusieurs événements.
Événements
| Événement | Quand |
|---|---|
message.received | Un client a envoyé un message, sur n’importe quel canal. |
message.sent | Un message de votre équipe, d’une automatisation, de l’IA ou de l’API est parti. |
message.delivered | Le téléphone ou l’application du client l’a reçu. |
message.read | Le client l’a lu (si le canal le signale). |
message.failed | Il n’a pas pu être envoyé ; la raison est incluse. |
conversation.started | Une nouvelle conversation a été ouverte. |
conversation.assigned / conversation.unassigned | La conversation a été attribuée, ou rendue à l’équipe. |
conversation.closed / conversation.reopened | La conversation a été fermée, ou rouverte. |
contact.created | Un nouveau contact, quelle que soit la source (message, import, formulaire, API). |
contact.tag_added / contact.tag_removed | Une étiquette a été ajoutée ou retirée. |
contact.stage_changed | Le contact a changé d’étape. |
contact.field_changed | Un champ personnalisé a changé. |
contact.consent_changed | Le contact a accepté ou refusé le marketing. |
template.status_changed | Meta a approuvé, rejeté ou suspendu un modèle WhatsApp. |
Les notes internes et les lignes système (« Ama a fermé cette conversation ») ne sont jamais envoyées comme messages.
Ce que PALMS envoie
Chaque appel est un POST avec Content-Type: application/json et ces en-têtes :
| En-tête | Signification |
|---|---|
x-palms-event | L’événement, par ex. message.received. |
x-palms-delivery | L’identifiant de cet envoi. Il reste le même quand PALMS réessaie ; Send again en crée un nouveau. |
x-palms-signature | t=<heure unix>,v1=<signature> — voir Vérifier la signature. |
User-Agent | PALMS-Webhooks/1 |
Le corps :
{
"id": "6f1c…",
"type": "message.received",
"createdAt": "2026-05-04T09:12:31.204Z",
"organizationId": "…",
"workspaceId": "…",
"data": {
"message": { "id": "…", "direction": "inbound", "type": "text", "text": "Bonjour, la formation est-elle encore ouverte ?", "…": "…" },
"conversation": { "id": "…", "status": "open", "channel": { "type": "whatsapp", "name": "Main" }, "…": "…" },
"contact": { "id": "…", "name": "Ama Mensah", "phone": "+233244440000", "…": "…" }
}
}idest l’identifiant de l’événement. Il ne change jamais, même quand PALMS réessaie ou que vous le renvoyez : utilisez-le pour ignorer les doublons.datautilise les mêmes formats que l’API PALMS. Les événements de contact ontdata.contactetdata.change(par exemple l’étiquette) ; ceux des modèles ontdata.template.- Les événements peuvent arriver dans le désordre (une nouvelle tentative peut arriver après un événement plus récent). Utilisez
createdAtsi l’ordre compte.
Vérifier la signature
PALMS signe <t>.<corps brut> avec HMAC-SHA256 et votre secret. Calculez la même chose et comparez. Refusez aussi les appels de plus de 5 minutes.
Node.js (Express)
const crypto = require('crypto');
app.post('/palms', express.raw({ type: 'application/json' }), (req, res) => {
const [t, v1] = req.get('x-palms-signature').split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', process.env.PALMS_WEBHOOK_SECRET).update(t + '.' + req.body).digest('hex');
const ok = expected.length === v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
if (!ok || Date.now() / 1000 - Number(t) > 300) return res.sendStatus(401);
const event = JSON.parse(req.body);
res.sendStatus(200); // répondez d’abord, puis faites le travail long
});PHP
$body = file_get_contents('php://input');
[$t, $v1] = array_map(fn($p) => explode('=', $p)[1], explode(',', $_SERVER['HTTP_X_PALMS_SIGNATURE']));
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('PALMS_WEBHOOK_SECRET'));
if (!hash_equals($expected, $v1) || time() - (int)$t > 300) { http_response_code(401); exit; }
$event = json_decode($body, true);
http_response_code(200);Utilisez le corps brut, tel que reçu : décoder puis ré-encoder le JSON le modifie et la signature ne correspond plus.
Pour changer le secret, ouvrez le webhook → Settings → Make a new secret. L’ancien cesse de fonctionner immédiatement : mettez votre serveur à jour tout de suite.
Nouvelles tentatives et désactivation
Si votre serveur ne répond pas 2xx en 10 secondes, PALMS réessaie après environ 1 minute, 5 minutes, 30 minutes, 1 heure, 2 heures, 4 heures, puis toutes les 8 heures — environ une journée au total. Ensuite, l’envoi est marqué Failed.
Si tous les appels d’un webhook échouent pendant 24 heures (et au moins 10 de suite), PALMS le désactive, abandonne ce qui attendait et prévient les Propriétaires et Administrateurs dans PALMS. Réparez votre serveur, cliquez sur Send test, puis Turn back on. Les événements survenus pendant la désactivation ne sont pas envoyés.
Mettre en pause un webhook (l’interrupteur dans Settings) fonctionne de la même façon : rien n’est mis en attente pendant la pause.
Le journal des envois
Cliquez sur un webhook pour voir chaque appel des 30 derniers jours : l’événement, la réponse de votre serveur, la durée, l’erreur en clair et le corps exact. Filtrez par Failed ou Retrying.
Cliquez sur Send again pour renvoyer un envoi avec le même identifiant d’événement et le même corps — utile après avoir corrigé un bug de votre côté.
Dépannage
| Ce que vous voyez | Que faire |
|---|---|
| « PALMS only calls https:// addresses » | Utilisez une adresse https. Let’s Encrypt fournit des certificats gratuits. |
| « …private address » / « …public address » | L’adresse pointe vers un réseau privé. Utilisez une adresse joignable depuis Internet. |
| 401 ou 403 | Votre serveur a refusé l’appel. Il ne doit pas exiger de connexion ; vérifiez plutôt la signature avec le bon secret. |
| 404 | Le chemin n’existe pas sur votre serveur. Vérifiez l’adresse. |
| 3xx (redirection) | PALMS ne suit pas les redirections. Utilisez l’adresse finale (souvent https:// au lieu de http://, ou avec/sans www). |
| 5xx ou « timed out » | Votre serveur a eu une erreur ou a été trop lent. Répondez 200 d’abord, puis faites le travail long en arrière-plan. |
| La signature ne correspond pas | Utilisez le corps brut, le secret actuel et t + "." + corps. |
| Doublons | Normal après une nouvelle tentative : ignorez les événements dont vous avez déjà traité l’id. |