Setting up webhooks

Create Server API key

From an admin account go to the Developers > API keys tab.
Add a new Server API key.
Copy the generate key somewhere safe on your machine. You will need it later in this tutorial, and we will reference it as <SERVER_API_KEY>.

Create Patient

Use the Create a Patient endpoint to create a new patient.

Request

curl --request POST \
     --url https://api.nabla.com/v1/server/patients \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <SERVER_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
     "first_name": "Jane",
     "last_name": "Doe",
     "locale": "fr",
     "email": "[email protected]",
     "phone": "33612356789",
     "date_of_birth": "1972-06-23",
     "sex": "FEMALE"
}
'

Response

Copy the <PATIENT_ID> (which is a UUID) from the response. You will need it later.

{
    "id": "<PATIENT_ID>",
    "username": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "locale": "fr",
    "email": "[email protected]",
    "phone": "33612356789",
    "sex": "FEMALE",
    "updated_at": "2022-06-15T13:37:39.034Z",
    "created_at": "2022-06-15T13:37:39.034Z"
}

Create Conversation

Use the Create a Conversation endpoint to create a new conversation.

Request

curl --request POST \
     --url https://api.nabla.com/v1/server/conversations \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <SERVER_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
     "patient_id": "<PATIENT_ID>"
}
'

Start ngrok

In order for our machine to be accessible from Nabla's server we will use ngrok.

Follow the installation guide on the official documentation to setup ngrok.
Once installed, launch it with ngrok http 8080, where 8080 is the port our locally launched node.js server (see later section on node.js server) will be listening to.
ngrok will give you an URL, that will be something like https://ebfb-2a01-cb08-59-fc00-c8e9-ff26-7c4a-eadf.eu.ngrok.io.

Create Webhook endpoint and put ngrok's URL there

From an admin account go to the Developers > Webhooks tab.
Click on Add a webhook, and put the ngrok URL you were given before. Don't forget to indicate the path in the URL as well, such as /my/custom/webhook/path.

Warning: If you relaunch ngrok and the URL changes, you will need to modify this newly created webhook to update the given URL.

Start node.js server

We will be using a very simple node.js express server in order to show you what webhook events look like, and how to parse them

Put the following in a file called server.js.

const bodyParser = require("body-parser");
const crypto = require("crypto");
const express = require("express");

// New app using express module
const app = express();

app.use(
  bodyParser.json({
    type: "application/json",
    verify: function (req, res, buf, encoding) {
      // Replace with your own Webhook Secret Key,
      // that you may find in https://pro.preprod.nabla.com/developers/webhooks
      const webhookSecretKey = "<WEBHOOK_SECRET_KEY>";

      const timestamp = req.headers["x-nabla-webhook-timestamp"];
      const receivedSignature = req.headers["x-nabla-webhook-signature"];

      const computedSignature = crypto
        .createHmac("sha256", webhookSecretKey)
        .update(timestamp + buf)
        .digest("hex");

      console.log("----- RECEIVED & COMPUTED SIGNATURES -----");
      console.log(`Received signature: ${receivedSignature}`);
      console.log(`Computed signature: ${computedSignature}`);
      console.log(
        `Do the signatures match? ${receivedSignature === computedSignature}`
      );
    },
  })
);

// Replace with your own Webhook path
// that you have setup in the Developers > Webhook tab.
app.post("/my/custom/webhook/path", function (req, res) {
  console.log("----- HEADERS -----");
  console.log(req.headers);

  console.log("----- PAYLOAD -----");
  console.log(req.body);

  res.writeHead(200);
  res.end();
});

const port = 8080;
app.listen(port, function () {
  console.log(`Server is running on port ${port}`);
});

Install both node.js and express.js on your machine.
Run the script with node server.js.

Send provider message and see event in logs

From a provider account in the Console, go to the Conversations tab, and send a message on the created conversation.
You should see your running node.js server log some output containing the event.

If you need further debugging, you can test the webhook events by sending test payload. In order to do that:

From an admin account go to the Developers > Webhooks tab.
Click on the ... menu for the webhook you are debugging.
Click on Send test payload.
Add some payload, such as { "message": "Hey there" }.
Click send.