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-Signatureheader 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)
rawBodymust be the exact bytes received. NeverJSON.parse/JSON.stringifybefore verifying. Express handlers must read the body withexpress.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:
| 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
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
- references/overview.md - SendX webhook concepts and event codes
- references/setup.md - Create a webhook and find the team API key
- references/verification.md - Signature verification details and gotchas