Security

To ensure that the webhook requests are genuinely from Magna and have not been tampered with, Magna uses HMAC signatures. Each request sent to your webhook endpoint includes a signature in the x-magna-signature header.

Signature Generation

Magna generates the signature using the following process:

1. Serialize the Request Body: The JSON payload is stringified.

2. Create HMAC Hash: An HMAC SHA1 hash is created using the generated secret.

3. Format the Signature: The final signature is prefixed with sha1= followed by the hexadecimal representation of the hash.

Verifying Signatures

To verify the integrity and authenticity of the incoming webhook requests, you must calculate the signature on your end and compare it with the x-magna-signature header provided in the request.

TypeScript Signature Calculation

import crypto from 'crypto';

/**
 * Calculates the HMAC SHA1 signature for the given request body.
 * @param body - The request payload received from Magna.
 * @param secret - The secret generated by Magna for this webhook.
 * @returns The formatted signature string.
 */
function calculateSignature(body: unknown, secret: string): string {
    const hmac = crypto.createHmac('sha1', secret);
    hmac.update(JSON.stringify(body));
    return `sha1=${hmac.digest('hex')}`;
}