# SendX Webhooks

## When to Use This Skill

* How do I receive SendX webhooks?
* How do I verify the `X-SendX-Signature` header on a SendX webhook?
* What is the secret for SendX webhook signature verification?
* How do I handle SendX open, click, bounce, spam, dropped, contact created and unsubscribe events?
* Why is my SendX webhook signature verification failing?

## Verification (core)

SendX sends `X-SendX-Signature: <hex>`: the **bare lowercase hex HMAC-SHA256 of the raw request body**,
with no prefix. The key is your **SendX team API key** (the same `X-Team-ApiKey` used for the REST API;
there is no separate webhook secret), used as UTF-8 bytes as-is. Nothing else is signed: no timestamp
or id, so there is no replay window to check. SendX also sends `X-SendX-Signature-Alg: hmac-sha256`.

Compare the whole header value as one digest. Validate its shape (exactly 64 hex characters), then
compare in constant time. Missing, empty, malformed or mismatched signature: answer `401`.

Node (check the hex shape first: `Buffer.from(x, 'hex')` silently drops invalid characters):

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

function verifySendxSignature(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== 'string' || !/^[0-9a-f]{64}$/i.test(signatureHeader)) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  return crypto.timingSafeEqual(Buffer.from(signatureHeader.toLowerCase(), 'hex'), expected);
}

```

Python (compare bytes, never `str`):

```python
import hashlib, hmac, re
from typing import Optional

def verify_sendx_signature(raw_body: bytes, signature_header: Optional[str], secret: str) -> bool:
    if not signature_header or not re.fullmatch(r"[0-9a-fA-F]{64}", signature_header):
        return False
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(bytes.fromhex(signature_header), expected)

```

> `rawBody` must be the exact bytes received. Never `JSON.parse`/`JSON.stringify` before verifying.
> Express handlers must read the body with `express.raw({ type: '*/*' })` so any content type verifies
> (Next.js: `await request.arrayBuffer()`; FastAPI: `await request.body()`).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendx-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendx-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendx-webhooks/examples/fastapi/).

## Events

SendX has no event-name strings. Dispatch on the body's top-level `type`, an **integer code**
(compare it as a number). Each engagement kind has one code per sending surface:

| Event | Campaign | Drip step | RSS | Workflow email | Seed contact |
| --- | --- | --- | --- | --- | --- |
| Mail opened | `7` | `32` | `172` | `189` | `271` |
| Link clicked | `8` | `33` | `173` | `190` | `272` |
| Mail bounced | `5` | `63` | `180` | `197` | `276` |
| Mail spam | `6` | `62` | `179` | `196` | `275` |
| Mail dropped | `60` | `61` | `178` | `195` | `278` |

Contact events: `ContactCreated` = `74`, `GlobalUnsubscribe` = `73`.

After verifying, treat every parsed field as untrusted: check the body is an object and `type` is
an integer before using it (the examples also tolerate a numeric string such as `"8"`, converting it
to a number). The docs only specify `type`; other body fields are not documented.

## Environment Variables

```bash
SENDX_WEBHOOK_SECRET=your_sendx_team_api_key   # SendX Settings → Team API Key

```

## Setup with Hookdeck

Hookdeck's source type is **SendX**, which verifies the signature.
Paste your SendX team API key. SendX signs webhooks with it.

> Paste your SendX team API key. SendX signs webhooks with it.

## Delivery

Respond in under 5 seconds (the docs' advice, not a stated timeout) and do heavy work asynchronously.
SendX retries failed deliveries: `X-SendX-Webhook-Attempt` carries the attempt number, but the retry
schedule is not documented. `X-SendX-Webhook-Id` identifies the delivery: use it for idempotency.

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sendx-webhooks/references/overview.md) - SendX webhook concepts and event codes
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sendx-webhooks/references/setup.md) - Create a webhook and find the team API key
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sendx-webhooks/references/verification.md) - Signature verification details and gotchas