Verify requests

PaySway signs each webhook request by computing an HMAC-SHA256 hash of the raw request body concatenated with a timestamp. This hash is generated using a secret value that only you and PaySway know. The resulting signature is provided in the X-PaySway-Signature header. By replicating this same process with your secret, you can confirm that the webhook request is authentic and has not been tampered with.

1. Obtain your secret

   When you create a webhook subscription, the response includes a secret field that is base64-encoded. You must decode this string before using it to generate an HMAC signature.

   JavaScript

   const base64Secret = "zTOJGr3vYdAHM/F5ZiDsVvgPZq5/Y3Ktbo9xw9Ncf8Y=";
   const decodedSecret = Buffer.from(base64Secret, "base64");
   

2. Extract the timestamp and signature

   PaySway includes an X-PaySway-Signature header in each webhook request. This header contains two key-value pairs separated by commas:

   • t: The UNIX timestamp of when the message was signed
   • v1: The actual signature in hexadecimal format

   Example Header

   Signature header

   X-PaySway-Signature: t=1738002855,v1=c9854765d242b9078e68b6fca1755f208ba70a7aa7c372abc4ec341483e34496
   

   Parse the header to extract the t and v1 values. Ignore any other values that may appear in the header.

   JavaScript

   const signatureHeader = "t=1738002855,v1=c9854765d242b9078e68b6fca1755f208ba70a7aa7c372abc4ec341483e34496";
   const segments = signatureHeader.split(",");
   const timestamp = segments.find(s => s.startsWith("t=")).substring(2);
   const signature = segments.find(s => s.startsWith("v1=")).substring(3);
   

3. Reconstruct the signing payload

   PaySway signs the combination of the timestamp and raw request body, separated by a period

   JavaScript

   const rawBody = '{"foo":"bar"}'; 
   const signingPayload = `${timestamp}.${rawBody}`;
   

   Do not parse or modify the request body before verification. Use the raw, unmodified payload exactly as received, preserving all whitespace and formatting.

4. Generate the expected signature

   Use your webhook secret to compute the HMAC-SHA256 hash of the signing payload. Convert the resulting hash to a hexadecimal string for comparison.

   JavaScript

   import { createHmac } from "crypto";
   // ...
   const expectedSignature = createHmac("sha256", decodedSecret)
     .update(signingPayload, "utf8")
     .digest("hex");
   

5. Verify the signature and timestamp

   Compare your expectedSignature with the v1 value from the X-PaySway-Signature header:

   • If they match: The request is authentic and was signed by PaySway using the correct secret
   • If they don’t match: Reject the request as potentially malicious or corrupted

   Additionally, use the timestamp t to implement replay attack protection by setting a maximum acceptable age for requests (e.g., 5 minutes).