Gareth Wilson Gareth Wilson

Guide to SendX Webhooks: Features and Best Practices

Published


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

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerx-sendx-signature
BodyJSON
Event routingBody field type

From SendX's webhook object reference and verification guide:

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

Eventtype
ContactCreated74
GlobalUnsubscribe73

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


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.