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
- You give PALMS an https:// address and choose the events you want.
- When one happens, PALMS sends a
POSTrequest with a JSON body describing it. - Your server answers with any 2xx status (200, 201, 204…) within 10 seconds to say “received”.
- 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
- Open Integrations → Webhooks and click Add webhook.
- Enter the address, for example
https://example.com/palms/webhook. It must start withhttps://and be reachable from the internet. Addresses inside a private network (192.168…,10…,localhost) are refused. - Choose the events. Start with only what you need; you can change them later.
- Copy the signing secret and put it in your server’s settings.
- Click Send test. PALMS sends a
pingevent; 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
| Event | When |
|---|---|
message.received | A customer sent a message, on any channel. |
message.sent | A message from your team, an automation, the AI or the API left PALMS. |
message.delivered | The customer’s phone or app received it. |
message.read | The customer read it (when the channel reports it). |
message.failed | It couldn’t be sent; the message includes the reason. |
conversation.started | A new conversation was opened. |
conversation.assigned / conversation.unassigned | Someone was given the conversation, or it went back to the team. |
conversation.closed / conversation.reopened | The conversation was closed, or opened again. |
contact.created | A new contact, from any source (a message, an import, a form, the API). |
contact.tag_added / contact.tag_removed | A tag was added or removed. |
contact.stage_changed | The contact moved to another stage. |
contact.field_changed | A custom field changed. |
contact.consent_changed | The contact opted in or out of marketing. |
template.status_changed | Meta 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:
| Header | Meaning |
|---|---|
x-palms-event | The event, e.g. message.received. |
x-palms-delivery | The id of this delivery. It stays the same when PALMS retries; Send again creates a new one. |
x-palms-signature | t=<unix time>,v1=<signature> — see Check the signature. |
User-Agent | PALMS-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", "…": "…" }
}
}idis the event id. It never changes, even when PALMS retries or you send it again: use it to ignore duplicates.datauses the same shapes as the PALMS API. Contact events havedata.contactanddata.change(for example the tag); template events havedata.template.- Events can arrive out of order (a retry can arrive after a newer event). Use
createdAtif 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 see | What 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 403 | Your server refused the call. It must not require a login; check the signature with the right secret instead. |
| 404 | The 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 match | Use the raw body, the current secret, and t + "." + body. |
| Duplicates | Normal after a retry: ignore events whose id you’ve already processed. |