# Guide to SendX Webhooks: Features and Best Practices

SendX is an email marketing platform for sending campaigns, drip sequences, RSS-to-email and automated workflows. Its webhooks report what recipients do with those emails, such as opening, clicking, bouncing or marking as spam, and when contacts are created or unsubscribe, so you can sync engagement into a CRM or suppress addresses elsewhere.

This guide explains SendX's subscription toggles and the numeric `type` codes they produce, the flat payload, signing with the team API key, and the delivery details SendX leaves open.

## What are SendX webhooks?

SendX webhooks belong to a team. You create one in the app or through the REST API, give it a URL, and switch on any of seven event groups: `contactCreated`, `unsubscribed`, `dropped`, `bounced`, `markedSpam`, `clicked` and `opened`.

What arrives isn't named the same way. Each delivery has an integer `type`, and SendX uses a different code for each sending surface. An open on a campaign email is `7`, but an open on a drip step email is `32`, and on a workflow email `189`. Your handler needs the full code table.

## SendX webhook features

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

From SendX's [webhook object reference](https://docs.sendx.io/api-reference/webhook/sendx-webhook-object) and [verification guide](https://docs.sendx.io/api-reference/webhook/verify-webhook):

* Deliveries are `POST` requests with a JSON body.
* `X-SendX-Signature` is signed with the **team API key**, the same one used for `X-Team-ApiKey` on the REST API.
* `X-SendX-Signature-Alg` names the algorithm, currently `hmac-sha256`.
* `X-SendX-Webhook-Id` identifies the delivery, and `X-SendX-Webhook-Attempt` counts attempts from `1`.
* SendX advises responding in under 5 seconds and handling retries gracefully.

## Events and payloads

Engagement events have a code per surface:

| Event routing | Body field `type` |

Contact events have a single code each:

| Event | `type` |
| --- | --- |
| ContactCreated | `74` |
| GlobalUnsubscribe | `73` |

The body is flat. Besides `type`, it has `time`, `data` and a set of nullable IDs that are filled when relevant: `contact_id`, `contact_email`, `campaign_id`, `drip_step_id`, `rss_exec_id`, `workflow_id`, `workflow_email_id`, `list_id`, `tag_id`, `link`, `provider_message_id` and others. Two details to watch:

* `data` is documented as a string, so parse it separately if it holds JSON.
* `time` is documented as milliseconds since the epoch, but the example value, `1686304219037565000`, is nanosecond-scale. Check the magnitude before converting.

SendX documents each field but doesn't publish a complete body, so capture one from a test send.

## Setting up SendX webhooks

1. In SendX, go to **Settings > Team API Key** and copy the key. Store it as `SENDX_TEAM_API_KEY`. It's the signing key too, and there is no separate webhook secret.
2. Create the webhook in the app, or call the API:

```bash
curl -X POST https://api.sendx.io/api/v1/rest/webhook \
  -H "X-Team-ApiKey: $SENDX_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "url": "https://example.com/webhooks/sendx", "opened": true, "clicked": true, "bounced": true, "markedSpam": true}'

```

`url` and `enabled` are required, and every event toggle defaults to `false`.

To route through Hookdeck, create a SendX source and use its URL as the webhook `url`. For the source's secret: Paste your SendX team API key. SendX signs webhooks with it. For local development:

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

```

## Securing SendX webhooks

SendX computes an HMAC-SHA256 of the raw JSON body using the team API key and sends it hex-encoded in `X-SendX-Signature`. SendX's own Python sample also rejects any `X-SendX-Signature-Alg` other than `hmac-sha256`. If verification fails, its troubleshooting advice is to check you're using the Team API Key rather than a personal or project key.

### 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-sendx-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  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 maps codes to an action and a surface, so one function handles all five kinds of open.

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

const SENDX_TYPES = {
  7: ['open', 'campaign'], 32: ['open', 'drip'], 172: ['open', 'rss'], 189: ['open', 'workflow'],
  8: ['click', 'campaign'], 33: ['click', 'drip'], 173: ['click', 'rss'], 190: ['click', 'workflow'],
  5: ['bounce', 'campaign'], 63: ['bounce', 'drip'], 180: ['bounce', 'rss'], 197: ['bounce', 'workflow'],
  6: ['spam', 'campaign'], 62: ['spam', 'drip'], 179: ['spam', 'rss'], 196: ['spam', 'workflow'],
  60: ['drop', 'campaign'], 61: ['drop', 'drip'], 178: ['drop', 'rss'], 195: ['drop', 'workflow'],
  74: ['contact_created', null], 73: ['unsubscribe', null],
};

const app = express();

app.post('/webhooks/sendx', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.SENDX_TEAM_API_KEY;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  let event;
  try {
    event = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
  try {
    const [action, surface] = SENDX_TYPES[event.type] || ['unknown', null];

    if (action === 'bounce' || action === 'spam' || action === 'unsubscribe') {
      await suppressions.add(event.contact_email, action);
    }
    await engagement.record(req.get('x-sendx-webhook-id'), action, surface, event);
  } catch {
    return res.sendStatus(503);
  }

  res.sendStatus(200);
});

```

Seed contact codes (271 to 278) are left out on purpose. They come from seed tests, not real recipients, and fall through to `unknown`.

A Hookdeck SendX source verifies requests the same way. It returns `200` to SendX and records mismatches as failed verification. SendX signs no timestamp, and Hookdeck adds no time window.

> **Make SendX webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) replies to SendX well within 5 seconds and absorbs the bursts of opens and clicks that follow a large campaign send.

## SendX webhook limitations and pain points

### Numeric codes per sending surface

**The Problem:** One subscription toggle produces up to five different `type` values.

**Why It Happens:** SendX's wire format gives each engagement event a separate code for campaigns, drip steps, RSS, workflow emails and seed contacts. The mapping from toggle to codes is implied by the groups in the reference, not stated.

**Workarounds:**

* Keep a lookup table like the one above and log codes it doesn't contain.
* Store the raw `type` as well as your mapped action.

**How Hookdeck Can Help:** Hookdeck filters can match lists of `type` values, so all opens or all bounces can go to one destination.

### The signing key is your team API key

**The Problem:** Every system that verifies SendX webhooks holds a key that can also call the SendX API.

**Why It Happens:** SendX has no separate webhook secret.

**Workarounds:**

* Keep verification in one service and pass verified events on internally.
* Treat a leak from that service as a full API key compromise.

**How Hookdeck Can Help:** Hookdeck can verify at ingestion, so your downstream services never need the team API key.

### Retry behaviour is undocumented

**The Problem:** You don't know how many times, or when, SendX retries.

**Why It Happens:** `X-SendX-Webhook-Attempt` shows that retries happen, but the schedule and which status codes count as success aren't documented.

**Workarounds:**

* Return `200` quickly, as the create-webhook page indicates.
* Deduplicate on `X-SendX-Webhook-Id`.

**How Hookdeck Can Help:** Hookdeck accepts each delivery first time, then retries your service under a policy you choose.

### An ambiguous timestamp

**The Problem:** Converting `time` as milliseconds gives a date far in the future.

**Why It Happens:** The field is documented as milliseconds, but the example is a nanosecond-scale number.

**Workarounds:**

* Detect the scale by the number of digits and divide accordingly.
* Use your own receive time if precision doesn't matter.

**How Hookdeck Can Help:** Hookdeck records when each request arrived, giving you a reliable receive timestamp alongside SendX's own.

## Best practices

### Act on suppressions immediately

Bounces, spam reports and unsubscribes should update your other sending systems quickly. Route them to a dedicated, fast path.

### Batch engagement events

Opens and clicks arrive in volume after a send. Queue them and write in batches. Our article on [asynchronous webhook processing](/webhooks/guides/why-implement-asynchronous-processing-webhooks) explains the pattern.

### Deduplicate deliveries

Store `X-SendX-Webhook-Id` so a retry doesn't double-count a click. See [webhook idempotency](/webhooks/guides/implement-webhook-idempotency) for implementation options.

### Use contact_email carefully

It's convenient for matching, but email addresses change. Prefer `contact_id` where your system stores it.

## Conclusion

SendX webhooks report email engagement and contact changes with numeric `type` codes that differ by sending surface, signed with a hex HMAC-SHA256 keyed by your team API key. Map the codes explicitly, protect the API key, and deduplicate on `X-SendX-Webhook-Id`, because retries happen on a schedule SendX doesn't publish.

[Hookdeck Event Gateway](https://hookdeck.com) verifies SendX requests, buffers campaign spikes and retries delivery to your services.

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