Authentication

Learn how to verify that incoming requests to your integration are authentically from Wavy Node.

Wavy Node uses HMAC-SHA256 to verify that incoming requests are authentic. All requests sent to your integration include the following headers:

Header	Description
x-wavynode-hmac	Base64 encoded HMAC-SHA256 signature of the request body
x-wavynode-timestamp	Timestamp of the request in milliseconds

Using @wavynode/utils

The easiest way to verify requests is with the validateSignature function:

import { validateSignature } from '@wavynode/utils';

const isValid = validateSignature({
    method: 'POST',
    path: '/webhook',
    body: req.body,
    timestamp: parseInt(req.headers['x-wavynode-timestamp']),
    secret: process.env.SECRET,
    timeTolerance: 300000,
    signature: req.headers['x-wavynode-hmac']
});

if (!isValid) {
    // The request is not from Wavy Node
    // or has been tampered with.
    // Reject the request.
}

validateSignature parameters

Parameter	Type	Description
method	string	The HTTP method of the request
path	string	The path of the request
body	object	The request body
timestamp	number	The timestamp from the x-wavynode-timestamp header
secret	string	Your integration’s secret from Project Settings in the dashboard
timeTolerance	number	Time tolerance in milliseconds to prevent replay attacks (recommended: 300000)
signature	string	The signature from the x-wavynode-hmac header

Manual authentication

If you are not using the @wavynode/utils package, you can implement the authentication logic yourself.

1. Create the canonical string

   Concatenate the following values separated by :::

   • The uppercase HTTP method (GET, POST, etc.)
   • The lowercase request path (e.g., /webhook)
   • The stringified request body with keys sorted alphabetically, or {} if no body
   • The timestamp from the x-wavynode-timestamp header

   GET::/users/123::{}::1757050233763
   
2. Create the HMAC signature

   Create a sha256 HMAC of the canonical string using your integration’s secret as the key. Base64 encode the result.

   import crypto from 'node:crypto';
   
   const createHmacSignature = (message, secret) => {
       const hmac = crypto.createHmac('sha256', secret);
       hmac.update(message);
       return hmac.digest('base64');
   };
   
3. Compare the signatures

   Compare the signature you created with the one from the x-wavynode-hmac header. If they match, the request is authentic.