Webhook signature verification
Shipmail signs every webhook delivery with HMAC-SHA256. Check the signature to make sure a request really came from Shipmail.
Last updated
Signature headers
| Header | Description |
|---|---|
| X-Shipmail-Signature | Hex-encoded HMAC-SHA256 signature. |
| X-Shipmail-Timestamp | When the delivery was signed, as a Unix timestamp in seconds. |
| X-Shipmail-Event-Id | Event ID. Use it to drop duplicates. |
Signed payload
Shipmail signs one string made of the timestamp and the raw request body:
v1={timestamp}\n{raw_body}The \n is a real newline character. The signature is the hex-encoded HMAC-SHA256 of this string, keyed with your webhook secret.
Node.js example
import { createHmac, timingSafeEqual } from "crypto";
function verifyWebhook(secret, signature, timestamp, body) {
// Reject stale deliveries (older than 5 minutes)
const age = Math.floor(Date.now() / 1000) - Number(timestamp);
if (Math.abs(age) > 300) {
return false;
}
const payload = `v1=${timestamp}\n${body}`;
const expected = createHmac("sha256", secret)
.update(payload)
.digest("hex");
if (expected.length !== signature.length) {
return false;
}
return timingSafeEqual(
Buffer.from(expected, "hex"),
Buffer.from(signature, "hex")
);
}Use timingSafeEqual to compare signatures. A plain string comparison is open to timing attacks.
Timestamp tolerance
Reject a delivery whose X-Shipmail-Timestamp is more than 5 minutes old. Then a captured request cannot be replayed later.
Event envelope
The request body is a JSON object with the same envelope for every event:
{
"event_id": "evt_abc123",
"event_type": "message.received",
"created_at": "2025-01-15T10:00:00.000Z",
"data": {
...
}
}Drop duplicates by event_id. The data field holds the payload for that event type.
Secret rotation
When you rotate a webhook secret with POST /v1/webhooks/:id/rotate-secret, deliveries also carry an X-Shipmail-Signature-Previous header, signed with the old secret, for 24 hours.
During those 24 hours, check both. Try the new secret first, then the previous signature. That way you can deploy the new secret without dropping a delivery.