Skip to content

Search documentation

Search pages and sections

API reference

Webhooks

Receive delivery, bounce, complaint, open and click events at your own endpoint, and verify the HulakiMail-Signature header.

Set up an endpoint

In Webhooks → Add endpoint, enter an HTTPS URL on your server and choose the events to receive. Each endpoint gets a signing secret (starts with whsec_) used to verify requests. Use Send test event to try your handler, and see every delivery attempt with its response in the dashboard.

Event types

EventSent when
email.sentThe email was handed to the delivery network
email.deliveredThe recipient’s mail server accepted it
email.delivery_delayedDelivery is being retried after a temporary failure
email.bouncedThe recipient’s server rejected it (bounce.type is permanent or transient)
email.complainedThe recipient reported it as spam
email.openedThe recipient opened it (requires open tracking)
email.clickedThe recipient clicked a link (requires click tracking)
email.failedIt could not be sent, e.g. a rendering error
email.suppressedIt was not sent because the recipient is suppressed
email.unsubscribedThe recipient unsubscribed via the email’s unsubscribe link

Payload

Every event is a JSON POST with the same envelope. Your tags and metadata are included.

POST /webhooks/hulakimail HTTP/1.1
Content-Type: application/json
HulakiMail-Signature: t=1763112612,v1=5f2b9c…

{
  "id": "evt_01JD3QB2M8T6W1Z4R9K7P3N5XC",
  "type": "email.delivered",
  "created_at": "2026-11-14T09:30:13Z",
  "data": {
    "email_id": "msg_01JD3Q8Z4X7M2V9K6T1R5B8N0C",
    "from": "[email protected]",
    "recipient": "[email protected]",
    "subject": "Welcome to Acme",
    "tags": ["welcome"],
    "metadata": { "user_id": "u_123" }
  }
}

Event-specific fields live in data — for example data.bounce (type, diagnostic) on bounces and data.click.url on clicks.

Verifying signatures

Anyone can send a request to your endpoint, so always verify the HulakiMail-Signature header before trusting a payload.

The algorithm

  1. Parse the header t=<unix timestamp>,v1=<hex signature>. There may be more than one v1 during secret rotation — accept if any matches.
  2. Build the signed string: the timestamp, a dot, and the raw request body — `${t}.${rawBody}`.
  3. Compute HMAC-SHA256 of that string with your endpoint’s signing secret, hex-encoded.
  4. Compare with a constant-time function, and reject timestamps more than 5 minutes from your clock to prevent replays.
Verify the exact bytes you received. Parsing and re-serialising the JSON first changes whitespace and key order and breaks the signature.

Code samples

import crypto from 'node:crypto';

// HulakiMail-Signature: t=1763112612,v1=5f2b…
export function verifyHulakiMailSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSec) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: use the raw body, not parsed JSON
app.post('/webhooks/hulakimail', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyHulakiMailSignature(
    req.body.toString('utf8'),
    req.get('HulakiMail-Signature') ?? '',
    process.env.HULAKIMAIL_WEBHOOK_SECRET,
  );
  if (!ok) return res.status(400).send('Invalid signature');

  const event = JSON.parse(req.body);
  // handle event.type …
  res.sendStatus(200);
});

The SDKs include this for you: hulakimail.webhooks.verify(rawBody, header, secret) in Node.js, \HulakiMail\Webhook::verify() in PHP, and the Laravel package verifies and dispatches events automatically.

Responses & retries

Respond with any 2xx status within 10 seconds to acknowledge an event. Other responses, timeouts and connection errors are retried with exponential backoff for up to 24 hours. Endpoints that keep failing are disabled automatically and the workspace owners are notified.

Best practices

  • Respond quickly and process events in a background job.
  • Make handlers idempotent — the same event can arrive more than once. Deduplicate on id.
  • Events can arrive out of order; use created_at when ordering matters.
  • Rotate the signing secret if it may have leaked; both secrets are valid for a short overlap.

Something unclear or missing? Tell us.