Overview

Introduction

Flow overview

Requirements

Versionning

Authentication

Server authentication

Incoming APIs

Overview

Provision user

Create encounter

Refresh encounter URL

Outgoing APIs

Overview

Callback authentication

Response protocol

Callback types

Reference

Changelog

1. HMAC Signature Verification (Recommended)

HMAC (Hash-based Message Authentication Code) verification is a lightweight but robust way to ensure that webhook requests genuinely originate from Nabla and have not been tampered with in transit.

You can retrieve your signature secret from the Nabla Connect Admin page.

Request headers

Every callback includes two authentication headers:

Verification steps

  1. Extract the timestamp and signature headers
  2. Reject if the timestamp is older than 60 seconds (prevents replay attacks)
  3. Concatenate the timestamp and the raw request body
  4. Compute HMAC-SHA256 using the shared signature secret
  5. Compare your computed HMAC with each signature in the header
  6. Reject with HTTP 401 if no match is found
  7. Reject if the callback event ID has already been processed (enforces idempotency)

JavaScript sample

const bodyParser = require("body-parser");
const crypto = require("crypto");
const express = require("express");
const app = express();
app.use(
  bodyParser.json({
    type: "application/json",
    verify: function (req, res, buf, encoding) {
      const webhookSecretKey = "<SIGNATURE_SECRET>";
      const timestamp = req.headers["x-nabla-connect-timestamp"];
      const receivedSignatures = req.headers["x-nabla-connect-signature"];
      const computedSignature = crypto
        .createHmac("sha256", webhookSecretKey)
        .update(timestamp + buf)
        .digest("hex");
      const signatureMatch = receivedSignatures
        .split(",")
        .some((sig) => sig.trim() === computedSignature);
      if (!signatureMatch) {
        console.error("Signature invalid");
        // respond with 401
      }
    },
  })
);

For more details, see RFC-2104 and RFC-4231.

2. OAuth 2.0 Client Credentials Flow

Nabla supports authenticating callback calls using the OAuth 2.0 Client Credentials Grant. When enabled, Nabla fetches a bearer access token from your OAuth authorization server and includes it in the Authorization header of each callback request.

This approach is especially useful for organizations already using OAuth-based authentication infrastructure.

To minimize load on your authorization server, Nabla caches and reuses access tokens as much as possible. We do not request a new token for every callback call. This ensures efficient use of resources and avoids excessive traffic to your auth infrastructure.

Configuration

Field Description
Authorization server endpoint The URL where Nabla requests access tokens.
Authentication Method Defines how credentials are sent (see below).
Client ID OAuth client identifier.
It will be sent as a ‘client_id’ form field or JSON field depending on the selected authentication method.
Client secret OAuth client secret.
It will be sent as a ‘client_secret’ form field or JSON field depending on the selected authentication method.

When Nabla requests a token from your authorization server, it sends the configured client credentials. You can choose between two methods for how those credentials are transmitted:

  1. Form URL-encoded (application/x-www-form-urlencoded) This is the default and most widely supported method (e.g. on Auth0, Okta), matching the standard behavior defined in RFC 6749 §4.4.2.

    POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=xxx&
client_secret=yyy

  2. JSON Body (application/json) This method sends the same data in a JSON payload. Choose this if your OAuth server expects or prefers JSON.

    POST /oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "xxx",
  "client_secret": "yyy"
}