Skip to content

WebhooksSignature verification

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

HeaderDescription
X-Shipmail-SignatureHex-encoded HMAC-SHA256 signature.
X-Shipmail-TimestampWhen the delivery was signed, as a Unix timestamp in seconds.
X-Shipmail-Event-IdEvent 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.