Documentation
Webhooks

Webhooks

A webhook sends an HTTP POST to your own server when something happens with your boards. Use it to feed your own dashboards, logs or automations.

Creating a webhook

  1. In the Palpable app, go to Settings → Developer → Webhooks.
  2. Choose New webhook.
  3. Give it a name and the URL that should receive it.
  4. Copy the signing secret the app shows, and keep it on your server.
  5. Choose the events you want.

Events

EventWhen it is sentdata
sensor_dataA reading arrives from a module{ "moduleId": "…", "value": … }
variable_changeA project's variables changeThe variables that changed, as { "name": value }
script_eventA script on a board sends an event{ "scriptEvent": "…", … } plus the event's own fields
device_statusA board connects or disconnects{ "deviceId": "…", "status": "connected" | "disconnected" }

sensor_data can be sent very often. Choose it only if your server expects a steady stream.

Payload

Every webhook is a POST with a JSON body:

{
  "event": "sensor_data",
  "timestamp": "2026-10-19T08:00:00.000Z",
  "data": { "moduleId": "modulino-thermo", "value": { "temperature": 23.5, "humidity": 45.2 } }
}

Checking the signature

When the webhook has a signing secret, each request carries an X-Palpable-Signature header: the HMAC-SHA256 of the raw request body, keyed with your secret, as lowercase hex (no prefix). Compute it over the exact bytes you received, before parsing the JSON.

import { createHmac, timingSafeEqual } from 'node:crypto'
 
// rawBody: the request body exactly as received (a Buffer or string)
function isFromPalpable(rawBody, signatureHeader) {
  const expected = createHmac('sha256', process.env.WEBHOOK_SECRET).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

Delivery and retries

  • Answer with any 2xx status to accept a delivery. Each request waits up to 10 seconds for your answer.
  • A 4xx answer is final: it is not retried.
  • A 5xx answer, a timeout or a network error is retried, a few seconds apart, up to 3 attempts in all.
  • Deliveries are capped per account per hour; past the cap, events are skipped until the hour is up.

Answer quickly and do slow work afterwards, so a busy server doesn't lose deliveries.