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 and verification guide:
- Deliveries are
POSTrequests with a JSON body. X-SendX-Signatureis signed with the team API key, the same one used forX-Team-ApiKeyon the REST API.X-SendX-Signature-Algnames the algorithm, currentlyhmac-sha256.X-SendX-Webhook-Ididentifies the delivery, andX-SendX-Webhook-Attemptcounts attempts from1.- 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:
datais documented as a string, so parse it separately if it holds JSON.timeis 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
- 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. - Create the webhook in the app, or call the API:
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:
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
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.
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 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
typeas 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
200quickly, 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 explains the pattern.
Deduplicate deliveries
Store X-SendX-Webhook-Id so a retry doesn't double-count a click. See 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 verifies SendX requests, buffers campaign spikes and retries delivery to your services.
Get started with Hookdeck for free and handle SendX webhooks reliably in minutes.