# 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)

```javascript
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)

```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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/xtremepush-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/xtremepush-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/xtremepush-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/xtremepush-webhooks/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](https://hookdeck.com/docs/sources#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](https://github.com/hookdeck/webhook-skills/blob/main/skills/xtremepush-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/xtremepush-webhooks/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

```bash
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

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/xtremepush-webhooks/references/overview.md) - Xtremepush webhook concepts, events, payload
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/xtremepush-webhooks/references/setup.md) - Configuring the webhook and Signed Payload auth
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/xtremepush-webhooks/references/verification.md) - Signature details, the timestamp window, and debugging