notification.updated

.md

Event POST <your callback URL>

A notification was delivered on one of its channels, or every channel failed (attempts says what happened on each).

Verify every callback

Check X-PaalChat-Signature on the raw body, reject timestamps older than 5 minutes, and de-duplicate on X-PaalChat-Delivery. Answer 2xx within 10 seconds. See Webhooks and callbacks.

Headers

X-PaalChat-Event string

X-PaalChat-Delivery string

Unique per event (equals body id). De-duplicate on it.

Format uuid.

X-PaalChat-Signature string

t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Reject if invalid or older than 300 seconds.

Pattern ^t=\d+,v1=[a-f0-9]{64}$.

Body

id string

Equals X-PaalChat-Delivery.

Format uuid.

sandbox boolean

true for sandbox businesses (test keys) - nothing reached WhatsApp.

event any

Always notification.updated.

occurred_at string

Format date-time.

business object

external_id string business.external_id

data object

notification_id integer data.notification_id

reference string | null data.reference

status string data.status

One of: delivered, failed.

channel string | null data.channel

attempts array of objects data.attempts

Language

Credentials

Signing secret $PAALCHAT_CALLBACK_SECRET

Receive and verify

PHP

// routes/api.php: Route::post('/paalchat/callback', PaalChatCallbackController::class);
public function __invoke(Request $request)
{
    $header = (string) $request->header('X-PaalChat-Signature');
    $raw = $request->getContent();

    if (! preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $header, $m)
        || abs(time() - (int) $m[1]) > 300
        || ! hash_equals(hash_hmac('sha256', $m[1].'.'.$raw, config('services.paalchat.callback_secret')), $m[2])) {
        abort(401);
    }

    // Process each delivery once.
    if (! Cache::add('paalchat:'.$request->header('X-PaalChat-Delivery'), true, now()->addDays(2))) {
        return response()->noContent();
    }

    $event = json_decode($raw, true);

    if ($event['event'] === 'notification.updated') {
        Alert::where('reference', $event['data']['reference'])->update(['status' => $event['data']['status'], 'channel' => $event['data']['channel']]);
    }

    return response()->noContent();
}

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/paalchat/callback', express.raw({ type: 'application/json' }), async (req, res) => {
  const raw = req.body.toString('utf8');
  const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(req.get('X-PaalChat-Signature') || '');
  const expected = m && crypto.createHmac('sha256', process.env.PAALCHAT_CALLBACK_SECRET).update(`${m[1]}.${raw}`).digest('hex');

  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300
      || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]))) {
    return res.sendStatus(401);
  }

  if (await seen(req.get('X-PaalChat-Delivery'))) return res.sendStatus(204); // process each delivery once

  const event = JSON.parse(raw);
  if (event.event === 'notification.updated') {
    await alerts.update(event.data.reference, { status: event.data.status, channel: event.data.channel });
  }
  res.sendStatus(204);
});

import hashlib, hmac, json, os, re, time
from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/paalchat/callback")
def paalchat_callback():
    raw = request.get_data()
    m = re.fullmatch(r"t=(\d+),v1=([a-f0-9]{64})", request.headers.get("X-PaalChat-Signature", ""))
    if not m or abs(time.time() - int(m[1])) > 300:
        abort(401)
    expected = hmac.new(os.environ["PAALCHAT_CALLBACK_SECRET"].encode(), m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, m[2]):
        abort(401)

    if seen(request.headers["X-PaalChat-Delivery"]):  # process each delivery once
        return "", 204

    event = json.loads(raw)
    if event["event"] == "notification.updated":
        alerts.update(event["data"]["reference"], status=event["data"]["status"], channel=event["data"]["channel"])
    return "", 204

require 'sinatra'
require 'openssl'
require 'json'

post '/paalchat/callback' do
  raw = request.body.read
  m = /\At=(\d+),v1=([a-f0-9]{64})\z/.match(request.env['HTTP_X_PAALCHAT_SIGNATURE'].to_s)
  halt 401 unless m && (Time.now.to_i - m[1].to_i).abs <= 300
  expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['PAALCHAT_CALLBACK_SECRET'], "#{m[1]}.#{raw}")
  halt 401 unless Rack::Utils.secure_compare(expected, m[2])

  halt 204 if seen?(request.env['HTTP_X_PAALCHAT_DELIVERY']) # process each delivery once

  event = JSON.parse(raw)
  if event['event'] == 'notification.updated'
    Alert.update_status(event.dig('data', 'reference'), event.dig('data', 'status'), event.dig('data', 'channel'))
  end
  status 204
end

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"math"
	"net/http"
	"os"
	"regexp"
	"strconv"
	"time"
)

var signature = regexp.MustCompile(`^t=(\d+),v1=([a-f0-9]{64})$`)

type Event struct {
	ID       string            `json:"id"`
	Event    string            `json:"event"`
	Business map[string]string `json:"business"`
	Data     map[string]any    `json:"data"`
}

func paalchatCallback(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body)
	m := signature.FindStringSubmatch(r.Header.Get("X-PaalChat-Signature"))
	if m == nil {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	t, _ := strconv.ParseInt(m[1], 10, 64)
	mac := hmac.New(sha256.New, []byte(os.Getenv("PAALCHAT_CALLBACK_SECRET")))
	mac.Write([]byte(m[1] + "." + string(raw)))
	if math.Abs(float64(time.Now().Unix()-t)) > 300 || !hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(m[2])) {
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}

	if seen(r.Header.Get("X-PaalChat-Delivery")) { // process each delivery once
		w.WriteHeader(http.StatusNoContent)
		return
	}

	var event Event
	json.Unmarshal(raw, &event)
	if event.Event == "notification.updated" {
		updateAlert(event.Data["reference"], event.Data["status"], event.Data["channel"])
	}
	w.WriteHeader(http.StatusNoContent)
}

Example payload

JSON

{
  "id": "3f4a5b6c-7d8e-4f9a-0b1c-2d3e4f5a6b7c",
  "event": "notification.updated",
  "occurred_at": "2026-10-02T11:04:20+00:00",
  "business": {"external_id": "presec"},
  "sandbox": false,
  "data": {
    "notification_id": 77,
    "reference": "closing-2026-10-02",
    "status": "delivered",
    "channel": "sms",
    "attempts": [
      {
        "channel": "whatsapp",
        "outcome": "failed: 131026",
        "message_id": 901,
        "at": "2026-10-02T11:00:02+00:00"
      },
      {
        "channel": "sms",
        "outcome": "sent",
        "message_id": 902,
        "at": "2026-10-02T11:00:03+00:00"
      }
    ]
  }
}