# Guide to Xtremepush Webhooks: Features and Best Practices

Xtremepush is a customer engagement platform for sending campaigns across email, mobile and web push, in-app messages and other channels. Its webhooks report what happens to each campaign message for each recipient, such as sends, deliveries, opens, unsubscribes and failures, and can also report subscription changes, so you can feed delivery data into a warehouse or keep consent in sync with your CRM.

This guide covers setting up the Webhooks integration, the event body and its custom formats, verifying `X-Xtremepush-Signature` through key rotations, and Xtremepush's five-second response limit.

## What are Xtremepush webhooks?

Xtremepush sends webhooks through a **Webhooks** integration in its marketplace. Each connection has a URL, an authentication type, the message events and channels to report, and optional subscription events. You can add several connections, for example to send failures to one endpoint and engagement events to another.

Each request is a JSON object with `event`, `time` and `properties`. Each message event's payload can also be edited per connection, which changes what your endpoint receives.

## Xtremepush webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-xtremepush-signature` |
| Body | JSON |
| Event routing | Body field `event` |

From Xtremepush's [Webhooks integration page](https://docs.xtremepush.com/docs/webhooks-integration-1):

* Authentication can be None, Basic Auth, Bearer Token, Signed Payload or OAuth 2.0 Token. Only Signed Payload produces a signature.
* Your endpoint must respond within five seconds or the delivery may fail.
* No retry policy is documented. **Notify on error** emails an address at regular intervals while failures continue.
* **Use static IP address** sends webhooks from the environment's static IP, so you can allowlist it.
* **external_message_id required** stops a webhook from being sent when that ID is missing.

## Events and payloads

Route on `event`.

| Event routing | Body field `event` |

Other message events cover opens, unsubscribes and failures, among others. Xtremepush keeps the full list in a separate Message Events section, and its webhook page names only these two as values. Subscription events report **Message opt-in/out** (unsubscribe headers, UI changes, imports and SDK updates) and **Preference opt-in/out** (preference centre changes, UI changes, imports and SDK updates).

In the default format, `time` is a Unix timestamp and `properties` holds:

| Property | Meaning |
| --- | --- |
| `message_type` | The channel |
| `campaign_id` | The campaign, searchable on the Existing Campaigns page |
| `profile_id` | Xtremepush's profile ID |
| `device_id` | The device ID, only for device-centric campaigns such as push and in-app |
| `trigger_id` | Xtremepush's ID for the action that triggered the send |
| `error_message` | Why a message failed, on failure events only |
| `user_id` | Your external user ID |
| `email` | The recipient's email address |
| `external_message_id` | Your transaction ID, if passed when executing the campaign through the API |

### Custom formats

**Each message event's payload can be edited per connection ("Custom format")**, so a customised connection may rename or drop `event`. Custom formats can add profile attributes through placeholders, and any placeholder with no data is sent as `null`. Use **Reset** in the editor to go back to the default.

## Setting up Xtremepush webhooks

1. In Xtremepush, go to **Settings > Integrations > Marketplace > Webhooks** and click **Connect**.
2. Name the connection and enter your URL, for example `https://example.com/webhooks/xtremepush`. It must start with `https://`.
3. Choose **Signed Payload** as the authentication type and copy the **Webhook Secret Key**. Store it as `XTREMEPUSH_WEBHOOK_SECRET`.
4. Select the message events, channels and any subscription events, then click **Connect**.

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

To route through Hookdeck, create an Xtremepush source with the Webhook Secret Key and use its URL in the connection. For local development:

```bash
npx hookdeck-cli listen 3000 xtremepush --path /webhooks/xtremepush

```

### HTTP method

Xtremepush says requests are sent with `Content-type: application/json` but doesn't name the HTTP method. Hookdeck's Xtremepush source pre-selects `POST` without managing the method, so allow other methods on the source if you see them. The receiver below uses `app.all`, verifies whatever method arrives, and acknowledges a verified empty body with `200`.

## Securing Xtremepush webhooks

With Signed Payload, every request carries `X-Xtremepush-Signature`, for example `t=1689343556,v1=<hex>,v1=<hex>`. Each `v1` is the hex HMAC-SHA256 of the timestamp, a dot and the JSON body, keyed with the Webhook Secret Key. Xtremepush advises ignoring any scheme other than `v1`.

When you generate a new key, it replaces the old one immediately, but Xtremepush keeps signing with the old key too for a fixed 24 hours. During that time there are two `v1` values, and a request is valid if either matches.

Xtremepush also advises rejecting requests whose timestamp is too old, without naming a tolerance. The verifier below doesn't apply one, and neither does Hookdeck.

### Node.js verification

```javascript
const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-xtremepush-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const parts = signature.split(',').map((part) => part.trim());
  const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
  if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
  const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
  const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The handler deduplicates on the event, campaign, profile, device and time, since there's no event ID.

```javascript
const express = require('express');

const app = express();

app.all('/webhooks/xtremepush', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.XTREMEPUSH_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
  if (!verifySignature(body, req.headers, secret)) return res.sendStatus(401);
  if (!body.length) return res.sendStatus(200);

  let message;
  try {
    message = JSON.parse(body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!message || typeof message !== 'object' || Array.isArray(message)) return res.sendStatus(400);
  if (typeof message.event !== 'string') return res.sendStatus(400);

  const props = message.properties && typeof message.properties === 'object' ? message.properties : {};
  const key = [message.event, props.campaign_id, props.profile_id, props.device_id, message.time]
    .map(String)
    .join('|');

  try {
    if (await alreadyHandled(key)) return res.sendStatus(200);
    await queue.add('xtremepush-event', { event: message.event, time: message.time, properties: props });
    await markHandled(key);
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

```

If you've customised a connection's format, change the field names here to match. `alreadyHandled` and `markHandled` stand in for whatever dedupe store you use, and `queue` for your job queue.

Hookdeck's Xtremepush source checks every `v1` value. A request that doesn't match is still acknowledged with `200`, then recorded as failed verification. Hookdeck applies no timestamp window.

> **Make Xtremepush webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) responds to Xtremepush well inside five seconds, keeps every message event, and retries your service when it's down, which Xtremepush doesn't document doing.

## Xtremepush webhook limitations and pain points

### No documented retries

**The Problem:** If your endpoint is down, message events may be lost.

**Why It Happens:** Xtremepush documents a five-second limit and error emails, but no retry policy.

**Workarounds:**

* Turn on **Notify on error** with an address someone watches.
* Reconcile campaign stats with Xtremepush's reports after an outage.

**How Hookdeck Can Help:** Hookdeck accepts each request at once and retries your service under a policy you set.

### Five seconds to respond

**The Problem:** Writing each event to a warehouse before responding can be too slow during large sends.

**Why It Happens:** Xtremepush expects a response within five seconds.

**Workarounds:**

* Queue the event and respond, as Xtremepush recommends.
* Batch warehouse writes in a worker.

**How Hookdeck Can Help:** Hookdeck absorbs bursts from large campaigns and can rate-limit delivery to your service.

### Custom formats change the body

**The Problem:** A teammate editing a message event's format can break your parser.

**Why It Happens:** Each message event's payload can be edited per connection, including renaming or removing `event`.

**Workarounds:**

* Keep the default format on the connection your code reads, or document custom formats alongside the code.
* Log and acknowledge bodies that don't match, instead of failing.

**How Hookdeck Can Help:** Hookdeck stores each body as received, so you can see exactly what changed and replay events after updating your parser.

### Only one auth type is signed

**The Problem:** Connections using None, Basic Auth, Bearer Token or OAuth send no signature.

**Why It Happens:** Only Signed Payload adds `X-Xtremepush-Signature`.

**Workarounds:**

* Use Signed Payload on every connection.
* Combine it with the static IP option if you also want network filtering.

**How Hookdeck Can Help:** Hookdeck's Xtremepush source records unsigned requests as failed verification. If a connection has to stay unsigned, leave verification off on its source.

## Best practices

### Check every v1

During a key rotation the header has two signatures. Accept the request if either matches.

### Build your own idempotency key

There's no event ID, so combine the event, campaign, profile, device and time, or pass `external_message_id` when executing campaigns through the API. Our [idempotency article](/webhooks/guides/implement-webhook-idempotency) has the details.

### Split connections by purpose

Separate connections for failures and engagement events let each endpoint scale and fail independently.

### Respond first

Store the event and return `200`, then process it. The [asynchronous processing guide](/webhooks/guides/why-implement-asynchronous-processing-webhooks) walks through queue design.

## Conclusion

Xtremepush reports per-recipient campaign events and subscription changes, signed with `t=` and one or two `v1=` values in `X-Xtremepush-Signature` when you choose Signed Payload. Respond within five seconds, check every `v1`, and plan for outages yourself, since no retry policy is documented.

[Hookdeck Event Gateway](https://hookdeck.com) verifies Xtremepush requests, absorbs campaign bursts and retries delivery to your systems.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Xtremepush webhooks reliably in minutes.