Agent skill

SendX Webhooks Skill

Receive and verify SendX webhooks. Use when setting up SendX webhook handlers, debugging X-SendX-Signature verification, or handling SendX email marketing events such as mail opens, link clicks, bounces, spam reports and new contacts.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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):

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

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/, examples/nextjs/, 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:

EventCampaignDrip stepRSSWorkflow emailSeed contact
Mail opened732172189271
Link clicked833173190272
Mail bounced563180197276
Mail spam662179196275
Mail dropped6061178195278

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

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

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

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →