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
| Event | Sent when |
|---|---|
| email.sent | The email was handed to the delivery network |
| email.delivered | The recipient’s mail server accepted it |
| email.delivery_delayed | Delivery is being retried after a temporary failure |
| email.bounced | The recipient’s server rejected it (bounce.type is permanent or transient) |
| email.complained | The recipient reported it as spam |
| email.opened | The recipient opened it (requires open tracking) |
| email.clicked | The recipient clicked a link (requires click tracking) |
| email.failed | It could not be sent, e.g. a rendering error |
| email.suppressed | It was not sent because the recipient is suppressed |
| email.unsubscribed | The 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
- Parse the header
t=<unix timestamp>,v1=<hex signature>. There may be more than onev1during secret rotation — accept if any matches. - Build the signed string: the timestamp, a dot, and the raw request body —
`${t}.${rawBody}`. - Compute HMAC-SHA256 of that string with your endpoint’s signing secret, hex-encoded.
- Compare with a constant-time function, and reject timestamps more than 5 minutes from your clock to prevent replays.
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);
});<?php
function verify_hulakimail_signature(string $payload, string $header, string $secret, int $tolerance = 300): bool
{
parse_str(str_replace(',', '&', $header), $parts);
$timestamp = (int) ($parts['t'] ?? 0);
if ($timestamp === 0 || abs(time() - $timestamp) > $tolerance) {
return false;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
return hash_equals($expected, (string) ($parts['v1'] ?? ''));
}
$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_HULAKIMAIL_SIGNATURE'] ?? '';
if (! verify_hulakimail_signature($payload, $header, getenv('HULAKIMAIL_WEBHOOK_SECRET'))) {
http_response_code(400);
exit('Invalid signature');
}
$event = json_decode($payload, true);
// handle $event['type'] …
http_response_code(200);import hashlib
import hmac
import time
def verify_hulakimail_signature(payload: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
try:
timestamp = int(parts.get("t", "0"))
except ValueError:
return False
if not timestamp or abs(time.time() - timestamp) > tolerance:
return False
signed = f"{timestamp}.".encode() + payload
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
# Flask
@app.post("/webhooks/hulakimail")
def hulakimail_webhook():
if not verify_hulakimail_signature(request.get_data(), request.headers.get("HulakiMail-Signature", ""), WEBHOOK_SECRET):
abort(400)
event = request.get_json()
# handle event["type"] …
return "", 200The 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_atwhen 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.