Step-by-Step Process for HMAC Signature Validation

Step-by-Step Process for HMAC Signature Validation

Step 1: Generate HMAC Signature Using the Shared WEBHOOK_SECRET

Before you start signing your payloads, you need to use the **WEBHOOK_SECRET** that we share to generate the HMAC signature. This key ensures secure communication between your system and ours.

1. Create the HMAC Signature

   • Use the shared **WEBHOOK_SECRET** to create the HMAC signature. This key is combined with the payload to produce the signature using the SHA-256 hashing algorithm. Here’s how you can create the HMAC signature:

     TypeScript

     const secretKey = WEBHOOK_SECRET; // Use the shared API_KEY
     const payload = JSON.stringify(data); // The data you want to send
     const signature = crypto.createHmac('sha256', secretKey)
                              .update(payload)
                              .digest('hex');
     

   • This signature will be included in the headers of your request under the capa-signature header to authenticate the payload.

2. Include the Signature in the Request

   • When making a request to our API, include the signature as a header:

Step 2: Verify the Payload Signature

When your system receives a payload, you should verify its authenticity by comparing the signature in the header with the one generated from the payload.

1. Extract the Signature from the Header

   • The signature will be sent in the capa-signature header:
     TypeScript

     const receivedSignature = req.headers['capa-signature'];
     

2. Compare the Signatures

   • Hash the received payload and compare it to the signature provided::
     TypeScript

     const hash = crypto.createHmac('sha256', secretKey).update(JSON.stringify(payload)).digest('hex');
     const isValid = crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(receivedSignature, 'hex'));
     

3. Process the Payload Based on Verification

   • If the signature matches, proceed with processing the payload. If it doesn’t, reject the request to prevent unauthorized actions

Summary of the Process

1. Generate HMAC Signature: Use the shared **WEBHOOK_SECRET** to generate an HMAC signature. Combine the payload with the **WEBHOOK_SECRET** and hash it using the SHA-256 algorithm.
2. Include Signature in the Request: Add the HMAC signature to the request header (capa-signature).
3. Verify Payload: When receiving a payload, compare the signature from the header with the hashed payload.

By following these steps, you can securely transmit and verify payloads using HMAC signatures, ensuring the integrity of the communication between your system and ours.