Module webhook

Webhook verification and decoding for mxRaven deliveries.

mxRaven signs every webhook delivery with HMAC-SHA256 over a canonical request string and sends the signature in X-MxRaven-* headers. A server that exposes a webhook endpoint verifies the request with a Verifier and decodes the JSON body:

const secret = process.env.MXRAVEN_WEBHOOK_SECRET;
if (secret === undefined || secret === "") {
  throw new Error("MXRAVEN_WEBHOOK_SECRET is required");
}

const verifier = new Verifier({ secret });

const event = await verifier.verifyAndDecode(request);
switch (event.type) {
  case eventType.inboundEmail:
    // A full inbound message.
    break;
  case eventType.deliveryStatus:
    // An SMTP delivery status.
    break;
  case eventType.storageStatus:
    // An object-storage delivery status.
    break;
}
Copy

The signing secret is shown only once, when the webhook endpoint is created or its secret is rotated. The secret is used as literal key bytes; do not base64-decode it.