Webhooks

Webhooks are a way for Sentinal to communicate with your application in real-time. Instead of making an API request to check the status of a resource, Sentinal will notify you of any changes.

Subscribing to Webhooks

To receive webhooks, you need to subscribe by providing a URL endpoint in your application that can accept POST requests

Subscribe to a client to receive webhooks

POST /v1/client/subscribeToClient

Headers

Name
Type
Description

x-api-key*

string

Request Body

Name
Type
Description

webhookUrl*

string

{
    "success": true,
    "message": "Webhook URL added successfully.",
    "content": {
        "clientId": "uAxxSaiTNDSYMrGdngEW",
        "webhookUrls": [
            "https://example.com/my-webhook-endpoint"
        ]
    }
}

Webhooks events

Sentinal will send a POST request to your webhook URL when the following events occur:

  1. Client Change: When there's an update to a client's data.

  2. New Basket: When a new basket is created.

  3. New Transaction: When a new transaction is initiated.

  4. Transaction Change: When there's an update to a transaction's data.

Verifying Webhook Requests

To ensure the integrity and authenticity of incoming webhook requests, it's crucial to verify the X-Signature header included in each request. This header contains a HMAC (Hash-based Message Authentication Code) signature, generated by applying the SHA-256 algorithm to the request payload using the client's secret as the key. By recreating this signature on the server receiving the webhook and comparing it with the signature in the X-Signature header, you can verify that the request is legitimate and hasn't been tampered with.

Step-by-Step Verification Process

  1. Extract the Payload from the Request: When your server receives a webhook request, first extract the payload, which is usually in JSON format.

  2. Retrieve the X-Signature Header: Extract the signature sent in the X-Signature header of the incoming request.

  3. Generate the Signature on Your Server:

    • Use the client's secret (the same secret used to generate the signature sent with the webhook) to create a HMAC signature of the payload. It's essential that the payload is stringified in the same manner as it was when the signature was generated if it's JSON, ensuring consistent formatting.

  4. Compare Signatures: Compare the signature you generated with the one received in the X-Signature header. If they match, the request is verified. If not, the request should be rejected as it may have been tampered with or not sent from the expected source.

Example Code

Below is an example function in Node.js that demonstrates how to verify the signature:

const crypto = require('crypto');

/**
 * Verifies the HMAC signature of the incoming webhook request.
 *
 * @param {string} payload - The raw JSON payload of the request as a string.
 * @param {string} receivedSignature - The signature extracted from the X-Signature header.
 * @param {string} secret - The client's secret used to generate the signature.
 * @return {boolean} - Returns true if the signature is verified, false otherwise.
 */
function verifySignature(payload, receivedSignature, secret) {
  // Generate HMAC SHA-256 signature of the payload
  const hmac = crypto.createHmac('sha256', secret);
  const generatedSignature = hmac.update(payload).digest('hex');

  // Compare the generated signature with the received signature
  return generatedSignature === receivedSignature;
}

// Example usage
const payload = '{"key":"value"}'; // This should be the raw string of the request body
const receivedSignature = 'the_signature_from_x_signature_header';
const secret = 'client_secret';

if (verifySignature(payload, receivedSignature, secret)) {
  console.log('Signature verified. Proceed with processing the request.');
} else {
  console.log('Signature verification failed. Do not process the request.');
}

Webhook Payloads

The payload of the webhook request will contain the full details of the resource that triggered the webhook. For example, if a new transaction is created, the payload will contain all the details of that transaction.

Handling Webhook Failures

If Sentinal receives a response other than a 200 OK from your webhook URL, it will consider the webhook delivery as failed. Make sure your application responds promptly and correctly to webhook requests to avoid missing any updates.

PreviousRegister Trade

Last updated