Agent skill

Xtremepush Webhooks Skill

Receive and verify Xtremepush webhooks. Use when setting up Xtremepush customer engagement webhook handlers, debugging X-Xtremepush-Signature verification, or handling campaign message events like message_send and message_delivery.

Install this skill

npx skills add hookdeck/webhook-skills --skill xtremepush-webhooks


When to Use This Skill

  • How do I receive Xtremepush webhooks?
  • How do I verify the X-Xtremepush-Signature header?
  • How do I handle message_send and message_delivery events?
  • Why is my Xtremepush webhook signature verification failing?
  • Why do Xtremepush deliveries fail verification with Basic Auth or Bearer Token?

Essential Code (USE THIS)

With the Signed Payload auth type, every delivery carries X-Xtremepush-Signature: t=<unix seconds>, v1=<hex>[, v1=<hex>]. Each v1 is the lowercase-hex HMAC-SHA256 of "<t>.<raw request body>", keyed with the Webhook Secret Key as UTF-8 bytes (not decoded). A second v1 appears for up to 24 hours after a key is replaced, so accept the request if any v1 matches. Ignore other keys such as v0; a header with no t fails.

Verification (Node.js)

const crypto = require('crypto');

// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' }), not express.json)
function verifyXtremepush(rawBody, signatureHeader, secret) {
  if (!secret || !signatureHeader) return false;
  let t; const v1 = [];
  for (const part of signatureHeader.split(',')) {
    const p = part.trim(), i = p.indexOf('=');
    if (i <= 0) continue;
    if (p.slice(0, i).trim() === 't') t = p.slice(i + 1).trim();   // keep t as the exact string
    else if (p.slice(0, i).trim() === 'v1') v1.push(p.slice(i + 1).trim());
  }
  if (!t || v1.length === 0) return false;
  // Optional replay window, off by default: retries and replays keep the original timestamp
  const expected = Buffer.from(crypto.createHmac('sha256', secret)
    .update(`${t}.`).update(rawBody).digest('hex'));
  // exactly 64 hex chars first, then equal-length constant-time compare
  return v1.some((s) => /^[0-9a-f]{64}$/i.test(s) &&
    crypto.timingSafeEqual(Buffer.from(s.toLowerCase()), expected));
}

Verification (Python)

import hashlib, hmac, re

def verify_xtremepush(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not secret or not signature_header:
        return False
    t, v1 = None, []
    for part in signature_header.split(","):
        k, sep, v = part.strip().partition("=")
        if sep and k.strip() == "t":
            t = v.strip()
        elif sep and k.strip() == "v1":
            v1.append(v.strip())
    if not t or not v1:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest().encode()
    # bytes on both sides: a non-ASCII header gives a failed match (401), not a TypeError (500)
    return any(re.fullmatch(rb"[0-9a-f]{64}", s.lower().encode()) and
               hmac.compare_digest(s.lower().encode(), expected) for s in v1)

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Timestamp window: off by default

t is Unix seconds. Hookdeck retries and replays resend the original headers and timestamp, so a fixed window rejects legitimate retries. The examples skip the freshness check unless you set XTREMEPUSH_WEBHOOK_TOLERANCE_SECONDS to a positive number of seconds (unset or 0 = off). Make the handler idempotent instead; see references/verification.md.

Any HTTP method

Xtremepush's docs don't name the HTTP method. Allow the method the sender uses on the Hookdeck source (see custom methods). The examples accept GET, POST, PUT, PATCH and DELETE on /webhooks/xtremepush, verify the signature first for every method, and treat a missing body as zero bytes (a verified GET with no body gets 200, not an invalid-JSON error).

Setup

Choose the Signed Payload auth type on the Xtremepush webhook and paste its Webhook Secret Key. Other auth types are unsigned and fail verification.

Hookdeck's source type is XTREMEPUSH (labelled "Xtremepush"), and Hookdeck's source verifies the signature. See references/setup.md for the full steps.

Event Types

Dispatch on the body's top-level event field (default body: event, time, properties).

EventTriggered When
message_sendA campaign message is sent to a recipient
message_deliveryA campaign message is delivered to a recipient

Handle these and log the rest. Each connection's payload can be edited ("Custom format"), so a customised connection may rename or drop event. Read every field defensively (check types before reading into the parsed body). See references/overview.md.

Important Headers

HeaderDescription
X-Xtremepush-Signaturet=<unix seconds>, v1=<hex HMAC-SHA256>[, v1=<hex>]; two v1 entries for up to 24 hours after a key is replaced

Environment Variables

XTREMEPUSH_WEBHOOK_SECRET=your_xtremepush_webhook_secret_key   # Webhook Secret Key from the Signed Payload auth type
XTREMEPUSH_WEBHOOK_TOLERANCE_SECONDS=0                         # optional; a positive value opts in to the replay window

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 xtremepush --path /webhooks/xtremepush

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →