Centre d’aide / Webhooks

Webhooks

PALMS appelle votre serveur dès qu’un message arrive, qu’une conversation est fermée ou qu’un contact change.

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

  1. Vous donnez à PALMS une adresse https:// et choisissez les événements voulus.
  2. Quand l’un d’eux se produit, PALMS envoie une requête POST avec un corps JSON qui le décrit.
  3. Votre serveur répond avec un statut 2xx (200, 201, 204…) en moins de 10 secondes pour dire « reçu ».
  4. 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

  1. Ouvrez Intégrations → Webhooks et cliquez sur Add webhook.
  2. Saisissez l’adresse, par exemple https://example.com/palms/webhook. Elle doit commencer par https:// et être joignable depuis Internet. Les adresses d’un réseau privé (192.168…, 10…, localhost) sont refusées.
  3. Choisissez les événements. Commencez par le strict nécessaire ; vous pourrez les modifier.
  4. Copiez le secret de signature et placez-le dans la configuration de votre serveur.
  5. 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énementQuand
message.receivedUn client a envoyé un message, sur n’importe quel canal.
message.sentUn message de votre équipe, d’une automatisation, de l’IA ou de l’API est parti.
message.deliveredLe téléphone ou l’application du client l’a reçu.
message.readLe client l’a lu (si le canal le signale).
message.failedIl n’a pas pu être envoyé ; la raison est incluse.
conversation.startedUne nouvelle conversation a été ouverte.
conversation.assigned / conversation.unassignedLa conversation a été attribuée, ou rendue à l’équipe.
conversation.closed / conversation.reopenedLa conversation a été fermée, ou rouverte.
contact.createdUn nouveau contact, quelle que soit la source (message, import, formulaire, API).
contact.tag_added / contact.tag_removedUne étiquette a été ajoutée ou retirée.
contact.stage_changedLe contact a changé d’étape.
contact.field_changedUn champ personnalisé a changé.
contact.consent_changedLe contact a accepté ou refusé le marketing.
template.status_changedMeta 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êteSignification
x-palms-eventL’événement, par ex. message.received.
x-palms-deliveryL’identifiant de cet envoi. Il reste le même quand PALMS réessaie ; Send again en crée un nouveau.
x-palms-signaturet=<heure unix>,v1=<signature> — voir Vérifier la signature.
User-AgentPALMS-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", "…": "…" }
  }
}
  • id est 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.
  • data utilise les mêmes formats que l’API PALMS. Les événements de contact ont data.contact et data.change (par exemple l’étiquette) ; ceux des modèles ont data.template.
  • Les événements peuvent arriver dans le désordre (une nouvelle tentative peut arriver après un événement plus récent). Utilisez createdAt si 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 voyezQue 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 403Votre serveur a refusé l’appel. Il ne doit pas exiger de connexion ; vérifiez plutôt la signature avec le bon secret.
404Le 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 pasUtilisez le corps brut, le secret actuel et t + "." + corps.
DoublonsNormal après une nouvelle tentative : ignorez les événements dont vous avez déjà traité l’id.

Toujours bloqué ?

Notre équipe répond sur WhatsApp, en français ou en anglais.

WhatsAppOuvrir Graphwafe