Help Centre / Webhooks

Webhooks

PALMS calls your server the moment a message arrives, a conversation closes or a contact changes.

A webhook is an address on your server (or in Zapier, Make or n8n) that PALMS calls the moment something happens: a customer writes, a message is delivered, a conversation is closed, a contact gets a tag. Your system doesn’t need to keep asking PALMS for news.

Only Owners and Admins can set up webhooks, in Integrations → Webhooks.

Overview

  1. You give PALMS an https:// address and choose the events you want.
  2. When one happens, PALMS sends a POST request with a JSON body describing it.
  3. Your server answers with any 2xx status (200, 201, 204…) within 10 seconds to say “received”.
  4. If it doesn’t, PALMS tries again later (see Retries).

Each call is signed with a secret only you and PALMS know, so your server can check it really came from PALMS.

Add a webhook

  1. Open Integrations → Webhooks and click Add webhook.
  2. Enter the address, for example https://example.com/palms/webhook. It must start with https:// and be reachable from the internet. Addresses inside a private network (192.168…, 10…, localhost) are refused.
  3. Choose the events. Start with only what you need; you can change them later.
  4. Copy the signing secret and put it in your server’s settings.
  5. Click Send test. PALMS sends a ping event; if your server answers 2xx you’ll see “It works”.

No server? In Zapier use “Webhooks by Zapier → Catch Hook”, in Make “Webhooks → Custom webhook”, in n8n the “Webhook” node. Paste the address they give you.

You can have up to 10 webhooks. One address can receive many events.

Events

EventWhen
message.receivedA customer sent a message, on any channel.
message.sentA message from your team, an automation, the AI or the API left PALMS.
message.deliveredThe customer’s phone or app received it.
message.readThe customer read it (when the channel reports it).
message.failedIt couldn’t be sent; the message includes the reason.
conversation.startedA new conversation was opened.
conversation.assigned / conversation.unassignedSomeone was given the conversation, or it went back to the team.
conversation.closed / conversation.reopenedThe conversation was closed, or opened again.
contact.createdA new contact, from any source (a message, an import, a form, the API).
contact.tag_added / contact.tag_removedA tag was added or removed.
contact.stage_changedThe contact moved to another stage.
contact.field_changedA custom field changed.
contact.consent_changedThe contact opted in or out of marketing.
template.status_changedMeta approved, rejected or paused a WhatsApp template.

Internal notes and system lines (“Ama closed this conversation”) are never sent as messages.

What PALMS sends

Every call is a POST with Content-Type: application/json and these headers:

HeaderMeaning
x-palms-eventThe event, e.g. message.received.
x-palms-deliveryThe id of this delivery. It stays the same when PALMS retries; Send again creates a new one.
x-palms-signaturet=<unix time>,v1=<signature> — see Check the signature.
User-AgentPALMS-Webhooks/1

The body:

{
  "id": "6f1c…",
  "type": "message.received",
  "createdAt": "2026-05-04T09:12:31.204Z",
  "organizationId": "…",
  "workspaceId": "…",
  "data": {
    "message": { "id": "…", "direction": "inbound", "type": "text", "text": "Hello, is the course still open?", "…": "…" },
    "conversation": { "id": "…", "status": "open", "channel": { "type": "whatsapp", "name": "Main" }, "…": "…" },
    "contact": { "id": "…", "name": "Ama Mensah", "phone": "+233244440000", "…": "…" }
  }
}
  • id is the event id. It never changes, even when PALMS retries or you send it again: use it to ignore duplicates.
  • data uses the same shapes as the PALMS API. Contact events have data.contact and data.change (for example the tag); template events have data.template.
  • Events can arrive out of order (a retry can arrive after a newer event). Use createdAt if order matters.

Check the signature

PALMS signs <t>.<raw body> with HMAC-SHA256 and your secret. Compute the same thing and compare. Also refuse calls older than 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); // answer first, then do the slow work
});

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);

Use the raw body exactly as received: parsing and re-encoding the JSON changes it and the signature won’t match.

To change the secret, open the webhook → Settings → Make a new secret. The old one stops working at once, so update your server straight away.

Retries and turning off

If your server doesn’t answer 2xx within 10 seconds, PALMS tries again after about 1 minute, 5 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, then every 8 hours — about a day in total. After that the delivery is marked Failed.

If every call to a webhook has failed for 24 hours (and at least 10 in a row), PALMS turns it off, drops what was waiting, and notifies Owners and Admins in PALMS. Fix your server, click Send test, then Turn back on. Events that happened while it was off are not sent.

Pausing a webhook (the switch in Settings) works the same way: nothing is queued while it’s paused.

The delivery log

Click a webhook to see every call from the last 30 days: the event, your server’s answer, how long it took, the error in plain words, and the exact body. Filter by Failed or Retrying.

Click Send again on a delivery to resend it with the same event id and body — useful after fixing a bug on your side.

Troubleshooting

What you seeWhat to do
“PALMS only calls https:// addresses”Use an https address. Free certificates are available from Let’s Encrypt.
“…private address” / “…public address”The address points inside a private network. Use an address reachable from the internet.
401 or 403Your server refused the call. It must not require a login; check the signature with the right secret instead.
404The path doesn’t exist on your server. Check the address.
3xx (redirect)PALMS doesn’t follow redirects. Use the final address (often https:// instead of http://, or with/without www).
5xx or “timed out”Your server had an error or was too slow. Answer 200 first, then do the slow work in the background.
Signature doesn’t matchUse the raw body, the current secret, and t + "." + body.
DuplicatesNormal after a retry: ignore events whose id you’ve already processed.

Still stuck?

Our team answers on WhatsApp, in English or French.

WhatsAppOpen Graphwafe