Webhooks

Overview

Webhooks are a way for our system to send real-time data to your application. They are typically triggered by events and will make an HTTP request to a URL you specify. This allows your application to receive and process data immediately as events occur.

Methods

We support the following HTTP methods for webhooks:

• POST: The primary method for webhooks, used to send data to your application.
• GET: Used to verify the endpoint during the setup process.

Headers

We have the ability to add additional headers to webhook requests. Here are our standard headers:

• "Content-Type": "application/json"
• "X-Hub-Signature": This is a sha256 HMAC signature of the body, created using JSON.stringify(payload, null, 0) and the provided Webhook secret.

Generating the X-Hub-Signature

The X-Hub-Signature header is used to verify the integrity and authenticity of the payload. It ensures that the payload has not been tampered with and that it is from a trusted source.

Example code to generate the X-Hub-Signature:

const crypto = require("crypto");

const secret = "your_webhook_secret"; // replace with your webhook secret
const payload = {
  /* your webhook payload */
};

const hmac = crypto.createHmac("sha256", secret);

hmac.update(JSON.stringify(payload, null, 0));

const signature = hmac.digest("hex");

console.log(signature);

Comparing Signatures

To verify that the incoming request is legitimate, you need to compare the X-Hub-Signature header from the request with your own generated signature. This comparison should be done in a time-safe manner to prevent timing attacks.

Here is an example of how to compare signatures in a time-safe manner:

const crypto = require("crypto");

const secret = "your_webhook_secret"; // replace with your webhook secret
const payload = {
  /* your webhook payload */
};
const receivedSignature = req.headers["x-hub-signature"]; // assuming you are using Express.js

const hmac = crypto.createHmac("sha256", secret);
hmac.update(JSON.stringify(payload, null, 0));
const calculatedSignature = hmac.digest("hex");

const timingSafeEqual = (a, b) => {
  const length = a.length > b.length ? a.length : b.length;
  let result = 0;
  for (let i = 0; i < length; i++) {
    result |= a.charCodeAt(i % a.length) ^ b.charCodeAt(i % b.length);
  }
  return result === 0;
};

if (timingSafeEqual(calculatedSignature, receivedSignature)) {
  console.log("Signatures match");
  // Process the webhook payload
} else {
  console.log("Signatures do not match");
  // Reject the request
}

This function ensures that the comparison is performed in a way that is resistant to timing attacks, which could otherwise be used to infer the signature.

Verifying the Request

When you receive a webhook request, you should perform the following steps to verify its authenticity:

1. Extract the X-Hub-Signature header from the request.
2. Generate a new HMAC signature using your webhook secret and the request payload.
3. Compare the received signature with the generated signature using a time-safe comparison function.

By following these steps, you can ensure that the request is legitimate and has not been tampered with.

Payloads

Webhooks are sent with the following general format:

{
  "eventType": "[EVENT_TYPE]",
  "payload": {}
}

Event Types

The [EVENT_TYPE] placeholder represents the type of event that triggered the webhook. Here are the possible event types:

1. new_transaction: Triggered when a new transaction occurs.
2. new_member: Triggered when a new member registers.
3. new_wallet: Triggered when a new wallet is created.
4. new_redemption: Triggered when a new redemption is made.
5. new_booking: Triggered when a new booking is made.
6. new_api_key: Triggered when a new API key is generated.
7. booking_status: Triggered when the status of a booking changes.
8. ingress_transaction: Triggered when an ingress transaction is recorded.
9. recalculate_tier: Triggered when a user's tier needs to be recalculated.
10. low_stock: Triggered when stock levels are low.

Example Payloads

To be confirmed, contact us for more details as required

Security Best Practices

• Always use HTTPS to ensure the security of the data in transit.
• Validate the payload structure and data types to ensure they match the expected format.
• Log webhook events for monitoring and debugging purposes.
• Implement retry logic in case of network issues or temporary failures on your endpoint.

By adhering to these best practices, you can enhance the security and reliability of your webhook integrations.