Webhooks: signed, ordered and retried.

PHP

<?php
// PHP 8+. UPPU webhook v1 (Standard Webhooks): raw body, raw key bytes, constant-time compare.
function uppu_verify_webhook(array $secrets, string $id, string $timestamp, string $body,
                             string $signatureHeader, int $tolerance = 300, ?int $now = null): bool
{
    if ($id === '' || !ctype_digit($timestamp) || abs(($now ?? time()) - (int) $timestamp) > $tolerance) {
        return false;
    }
    $signed = $id . '.' . $timestamp . '.' . $body;
    foreach ($secrets as $secret) {
        if (!is_string($secret) || strncmp($secret, 'whsec_', 6) !== 0) {
            continue;
        }
        $key = base64_decode(substr($secret, 6), true);          // raw bytes, not the text
        if ($key === false || $key === '') {
            continue;
        }
        $expected = base64_encode(hash_hmac('sha256', $signed, $key, true));
        foreach (explode(' ', $signatureHeader) as $part) {
            [$version, $signature] = array_pad(explode(',', $part, 2), 2, '');
            if ($version === 'v1' && hash_equals($expected, $signature)) {
                return true;
            }
        }
    }
    return false;
}

// Receiver. Apache and nginx + PHP-FPM pass "webhook-id" as $_SERVER['HTTP_WEBHOOK_ID'].
$header = fn (string $name): string => (string) ($_SERVER['HTTP_' . strtoupper(str_replace('-', '_', $name))] ?? '');
$body = (string) file_get_contents('php://input');               // raw body, unmodified
$secrets = array_filter([getenv('UPPU_WEBHOOK_SECRET') ?: '', getenv('UPPU_WEBHOOK_SECRET_OLD') ?: '']);

if (!uppu_verify_webhook($secrets, $header('webhook-id'), $header('webhook-timestamp'), $body, $header('webhook-signature'))) {
    http_response_code(401);                                     // the activation probe expects a non-2xx
    exit;
}
$event = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
// 1) drop repeats by $event['id']  2) queue the work  3) answer quickly
http_response_code(204);

Node.js

// Node.js 18+, no dependencies. Read the raw body before any JSON parser.
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyUppuWebhook(secrets, id, timestamp, rawBody, signatureHeader,
                                  toleranceSec = 300, nowSec = Date.now() / 1000) {
  if (!id || !/^[0-9]+$/.test(timestamp ?? '')) return false;
  if (Math.abs(nowSec - Number(timestamp)) > toleranceSec) return false;
  const signed = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const given = (signatureHeader ?? '').split(' ').flatMap((part) => {
    const comma = part.indexOf(',');
    return comma > 0 && part.slice(0, comma) === 'v1' ? [Buffer.from(part.slice(comma + 1), 'utf8')] : [];
  });
  for (const secret of secrets) {
    if (typeof secret !== 'string' || !secret.startsWith('whsec_')) continue;
    const key = Buffer.from(secret.slice(6), 'base64');           // raw bytes, not the text
    if (key.length === 0) continue;
    const expected = Buffer.from(createHmac('sha256', key).update(signed).digest('base64'), 'utf8');
    if (given.some((sig) => sig.length === expected.length && timingSafeEqual(sig, expected))) return true;
  }
  return false;
}

const secrets = [process.env.UPPU_WEBHOOK_SECRET, process.env.UPPU_WEBHOOK_SECRET_OLD].filter(Boolean);

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const raw = Buffer.concat(chunks);                            // raw bytes; do not re-serialise
    const ok = verifyUppuWebhook(secrets, req.headers['webhook-id'], req.headers['webhook-timestamp'],
      raw, req.headers['webhook-signature']);
    if (!ok) { res.writeHead(401).end(); return; }               // the activation probe expects a non-2xx
    const event = JSON.parse(raw.toString('utf8'));
    // drop repeats by event.id, queue the work, then answer quickly
    res.writeHead(204).end();
  });
}).listen(8080);                                                  // behind your HTTPS reverse proxy (port 443)

Python

# Python 3.9+, standard library only.
import base64
import hashlib
import hmac
import json
import os
import re
import time
from http.server import BaseHTTPRequestHandler, HTTPServer


def verify_uppu_webhook(secrets, msg_id, timestamp, raw_body, signature_header, tolerance=300, now=None):
    if not msg_id or not timestamp or not re.fullmatch(r"[0-9]+", timestamp):
        return False
    if abs((time.time() if now is None else now) - int(timestamp)) > tolerance:
        return False
    signed = f"{msg_id}.{timestamp}.".encode("utf-8") + raw_body
    given = []
    for part in (signature_header or "").split(" "):
        version, _, signature = part.partition(",")
        if version == "v1" and signature:
            given.append(signature.encode("utf-8"))
    for secret in secrets:
        if not secret or not secret.startswith("whsec_"):
            continue
        key = base64.b64decode(secret[len("whsec_"):])           # raw bytes, not the text
        expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
        if any(hmac.compare_digest(expected, signature) for signature in given):
            return True
    return False


class Receiver(BaseHTTPRequestHandler):
    secrets = [s for s in (os.environ.get("UPPU_WEBHOOK_SECRET"), os.environ.get("UPPU_WEBHOOK_SECRET_OLD")) if s]

    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))   # raw bytes; do not re-serialise
        ok = verify_uppu_webhook(self.secrets, self.headers.get("webhook-id"),
                                 self.headers.get("webhook-timestamp"), raw, self.headers.get("webhook-signature"))
        if not ok:
            self.send_response(401)                              # the activation probe expects a non-2xx
            self.end_headers()
            return
        event = json.loads(raw)
        # drop repeats by event["id"], queue the work, then answer quickly
        self.send_response(204)
        self.end_headers()


if __name__ == "__main__":
    HTTPServer(("127.0.0.1", 8080), Receiver).serve_forever()   # behind your HTTPS reverse proxy (port 443)

cURL

curl -sS "$UPPU_API_BASE/events?after=01jace0e1v2m4n6p8q0r2s4t6a&types=message.received,message.status&limit=100" \
  -H "Authorization: Bearer $UPPU_API_KEY"

PHP

// Uses uppu_request() from the quickstart; load/save/handle are your own functions.
$after = load_last_event_id();                       // '' the first time
while (true) {
    $query = http_build_query(array_filter(['after' => $after, 'types' => 'message.received,message.status', 'limit' => 100]));
    $r = uppu_request('GET', 'events?' . $query);
    if ($r['status'] === 422 && $after !== '') {     // unknown or older than 7 days: start again
        $after = '';
        continue;
    }
    if ($r['status'] !== 200) {
        break;                                       // try later (429: after Retry-After)
    }
    foreach ($r['body']['data'] as $event) {
        handle_event_once($event);                   // the same de-duplication as your receiver
        $after = $event['id'];
    }
    save_last_event_id($after);
    if ($r['body']['next_cursor'] === null) {
        break;
    }
    usleep(600000);                                  // stay under 2 requests a second
}

Node.js

// Uses uppuRequest() from the quickstart; load/save/handle are your own functions.
let after = await loadLastEventId();                 // '' the first time
for (;;) {
  const query = new URLSearchParams({ types: 'message.received,message.status', limit: '100' });
  if (after) query.set('after', after);
  const { status, data } = await uppuRequest('GET', `events?${query}`);
  if (status === 422 && after) { after = ''; continue; }   // unknown or older than 7 days: start again
  if (status !== 200) break;                               // try later (429: after Retry-After)
  for (const event of data.data) {
    await handleEventOnce(event);                          // the same de-duplication as your receiver
    after = event.id;
  }
  await saveLastEventId(after);
  if (data.next_cursor === null) break;
  await new Promise((resolve) => setTimeout(resolve, 600)); // stay under 2 requests a second
}

Python

# Uses uppu_request() from the quickstart; load/save/handle are your own functions.
import time
from urllib.parse import urlencode

after = load_last_event_id()                         # "" the first time
while True:
    params = {"types": "message.received,message.status", "limit": 100}
    if after:
        params["after"] = after
    status, page = uppu_request("GET", "events?" + urlencode(params))
    if status == 422 and after:                      # unknown or older than 7 days: start again
        after = ""
        continue
    if status != 200:
        break                                        # try later (429: after Retry-After)
    for event in page["data"]:
        handle_event_once(event)                     # the same de-duplication as your receiver
        after = event["id"]
    save_last_event_id(after)
    if page["next_cursor"] is None:
        break
    time.sleep(0.6)                                  # stay under 2 requests a second