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-Signatureheader? - How do I handle
message_sendandmessage_deliveryevents? - 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_ 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).
| Event | Triggered When |
|---|---|
message_send | A campaign message is sent to a recipient |
message_delivery | A 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
| Header | Description |
|---|---|
X-Xtremepush-Signature | t=<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
- references/overview.md - Xtremepush webhook concepts, events, payload
- references/setup.md - Configuring the webhook and Signed Payload auth
- references/verification.md - Signature details, the timestamp window, and debugging