Callbacks

To ensure the authenticity and security of callback notifications sent from our API to your systems, each notification includes a signature in the HTTP headers under the key signature. This signature allows you to validate that the notification originated from us and was not tampered with during transmission.

Signature Generation

1. Payload and Customer Identification

Each notification has a unique payload (payload) and is associated with a specific customer (customerUuid).

2. Data to Be Signed

We concatenate the payload and customer UUID in the following format: {payload}+{customerUuid}

• payload: The JSON stringified body of the callback notification. • customerUuid: The unique identifier of your account.

3. Key for Signing

We use a secret API key (api_key) associated with your account to generate the signature. This key is securely stored and unique for each customer.

4. Hash Algorithm

We use the HMAC (Hash-Based Message Authentication Code) algorithm with SHA-256 to compute the signature. The formula is:

signature = HMAC_SHA256(api_key, "{payload}+{customerUuid}")

5. Output:

The resulting HMAC digest is converted to a hexadecimal string and sent as the signature header.

Example Notification Header

http
POST /callback-endpoint HTTP/1.1
Content-Type: application/json
signature: 3d2e4a5b6c7d8e9f10g11h12i13j14k15l16m17n18o19p20q21r22s23t24u25

Validating the Signature on Your Side

To validate the authenticity of a callback notification follow this steps:

1. Retrieve the Header Signature

Extract the signature from the headers of the received notification.

2. Recreate the Signature

Using your API key (shared during account setup), and your customer UUID recreate the signature following the same process we use:

• JSON stringify the payload exactly as received. • Concatenate the payload and customer UUID with a +. • Compute the HMAC using the SHA-256 algorithm and your API key.

Example in Node.js:

const crypto = require('crypto');

const apiKey = 'your-api-key'; // The secret API key we provided
const payload = '{"event":"payment","amount":100}'; // The callback payload (JSON stringified)
const customerUuid = 'abc123'; // Your customer UUID

const dataToSign = `${payload}+${customerUuid}`;
const hmac = crypto.createHmac('sha256', apiKey);
hmac.update(dataToSign);
const recreatedSignature = hmac.digest('hex');

console.log('Recreated Signature:', recreatedSignature);

3. Compare Signatures

• Compare the recreatedSignature with the signature header value. • If they match, the notification is valid and originated from our API. If not, reject the notification.

Example in Node.js

const crypto = require('crypto');

const apiKey = Buffer.from('your-api-key', 'utf-8'); // The secret API key
const payload = '{"event":"payment","amount":100}'; // The callback payload (JSON stringified)
const customerUuid = 'abc123'; // The customer UUID

const dataToSign = ${payload}+${customerUuid};
const recreatedSignature = crypto
  .createHmac('sha256', apiKey) // Create an HMAC using the SHA-256 algorithm and the API key
  .update(dataToSign, 'utf-8') // Specify the data to sign
  .digest('hex'); // Generate the hash in hexadecimal format

// Assume header.signature is the signature sent in the request headers
const header = { signature: 'signature-sent-in-header' }; // Placeholder for the header

const isValidSignature = recreatedSignature === header.signature; // Validate the signature

console.log('Is the signature valid?', isValidSignature);

Security Notes

• API Key Confidentiality: Keep your API key secure and never expose it publicly or hard-code it into client-side code.

• Validate Payload Integrity: If the signature does not match, reject the notification and log the attempt.

By following these steps, you can ensure that the callback notifications you receive are authentic and trustworthy. If you have any issues or questions, please contact our support team.