Configuring and Using Webhooks

Webhooks enable your application to receive real-time notifications whenever specific events occur in AndDone. Instead of polling the API for updates, you can configure an HTTPS endpoint on your server that listens for requests containing event data. This guide walks you through the steps needed to begin using webhooks.

Step 1. Create a webhook endpoint on your server

Set up an HTTPS endpoint function on your server that can accept webhook requests with a POST method. Your endpoint should:

• Accept POST requests with a JSON payload (event object).
• Quickly return a success status code (2xx) when a webhook notification is received and validated. The endpoint should return the status code before performing any additional processing of the payload data.
• Include functionality to enqueue or log events for later processing as necessary, rather than blocking incoming events during processing.

Step 2. Generate an HMAC secret key for webhook validation

Each incoming webhook event must be validated to ensure it comes from AndDone and hasn't been modified. You do this by generating a strong HMAC secret which is shared with AndDone and used to validate incoming requests. You will need to provide this value when registering your webhook endpoint and subscribing to webhook modules in the AndDone Agent Portal. Your HMAC key should be hex-based and no more than 250 characters.

You can generate an HMAC key using the method of your choice. The following are examples of commands you can use to generate an HMAC secret in macOS/Linux, Windows PowerShell, and Node.js:

macOS/Linux

openssl rand -hex 32

Windows PowerShell

[System.Convert]::ToHexString((1..32 | ForEach-Object {Get-Random -Maximum 256}))

Node.js

require('crypto').randomBytes(32).toString('hex');

Store your HMAC keys in a secure location such as in an environment variable or secrets manager. Rotate HMAC keys periodically, especially after staff changes.
Subscribing to Webhooks

To receive webhook notifications for a specific event, subscribe to the corresponding webhook event module in the AndDone Merchant Portal.

Step 3. Register your Webhook Endpoint in the Agent Portal

Once you have configured a webhook endpoint on your server, you must register it in the AndDone agent portal to begin receiving webhook events.

To register your webhook endpoint.

1. In the left column of the Merchant Portal, select Developer > Webhooks. The Webhook Management screen is displayed.
2. Click the Add Webhook button. The New Webhook Endpoint window is displayed.
3. In the URL field, enter the URL for your webhook endpoint.
4. Click the Modules field, and select the checkbox beside each module that you want to subscribe to for the given endpoint.
5. Click the Version field, and select the version of the selected webhook modules that you want to subscribe to.
6. In the Authentication Types field, enter the type of authentication used by your endpoint.
7. Depending on the selected authentication type, enter the required authentication parameters in the displayed fields.
8. In the HMAC Key field enter the Hash-based Message Authentication Code key that will be used to validate the integrity and authenticity of webhook payloads.
9. Click Save. The endpoint is registered with the selected webhook module subscriptions.

After saving, your endpoint is active and will begin receiving subscribed events.

Step 4. Verify webhook requests

Every webhook request includes an HMAC Signature which is used to validate that the request was sent by AndDone. This signature is calculated using the HMAC secret that you shared with AndDone when registering your webhook endpoint and the event object. Your server must recompute this signature using the raw request body and your shared HMAC secret, then compare it to the provided value in the webhook payload. If the your calculated value and the the value in the webhook payload match, then you know that the request is valid.

To verify requests:

• Compare the digest against the signature header value.
• Use HMAC-SHA256 with your secret to compute a digest.
• Read the raw request body (before JSON parsing).
• Acknowledge valid requests by sending a 200 Success status code.
• Reject any invalid requests and send a 401 Unauthorized status code.

Example in .NET (NuGet package):

using AndDone.HmacValidator;

var validator = new HmacValidator();
bool isValid = validator.IsValidHmac(secretKey, webhookNotification);

if (isValid) {
    // process payload
} else {
    return Unauthorized();
}

Example in Node.js (manual):
const crypto = require("crypto");

function verifySignature(secret, body, signatureHeader) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}