Introduction

Before any events are sent to a webhook, MedChat verifies the organization's ownership of the webhook endpoint by performing the webhook endpoint verification process described below.

🚧

Existing Webhooks

Webhooks last updated prior to 1/21/2022 are not subject to endpoint verification. Once an existing webhook is updated in MedChat, it becomes subject to endpoint verification, and it will no longer receive events until it passes verification.

All newly created webhooks are subject to endpoint verification.

Verifying the Webhook Endpoint

The organization's ownership of a webhook's endpoint URL must be verified before MedChat will send any events to it. This process utilizes the webhook's secret coupled with the well-known HMACSHA256 algorithm to generate a response to a challenge code.

The Verification Process

1. MedChat generates a string that will serve as the challengeCode.
2. MedChat issues an HTTP GET request to the webhook endpoint, including the challengeCode as a querystring parameter.

GET https://example.com/webhook?challengeCode=b0d7d62e-2ca5-4928-a8ab-56850cd54126

3. Your service computes the challengeResponse, which is the hex-encoded HMACSHA256 signature for the challengeCode, using your webhook's secret as the secret key. Return both the challengeCode and challengeResponse in a JSON payload with a 200 OK status within 3 seconds:

{
  "challengeCode": "b0d7d62e-2ca5-4928-a8ab-56850cd54126",
  "challengeResponse": "A71r27obVGYehYvO2ggeSi9wUo9m/bI1WOUwJfrD+Do="
}

4. Upon receiving the verification response, MedChat computes the expected challenge response and compares it with the challengeResponse returned by your service.
5. If the challengeResponse is successfully verified, MedChat switches the verification status on the webhook to "Verified" and the subscribed events will start flowing to your webhook.

📘

Webhook endpoint verification occurs when a webhook is created or updated. Webhooks that have been previously verified are re-verified roughly every two hours.

Reverification

Verified webhook endpoints are reverified roughly every two hours. If a webhook fails reverification three times in a row, three things will occur:

1. Its verification status with change from "Verified" to "Unverified."
2. Events will stop flowing to the webhook.
3. Users for the organization with either the OrgOwner or Developer role will receive an e-mail indicating that the webhook has become unverified.

After resolving the issue that caused the webhook to become unverified, the developer can manually trigger another verification from the Developer > Webhooks screen in MedChat.

📘

Testing Webhooks

You can use an URL from https://webhook.site/ as your endpoint to verify that your webhook is sending events and inspect their payloads prior to setting up endpoint verification. This test domain is whitelisted in MedChat and not subject to endpoint verification.

This should only be used for short periods while testing with non-production data.

Example Implementation

The following is an example C# implementation of the challenge response computation:

using System;
using System.Security.Cryptography;
using System.Text;


public static string ComputeChallengeResponse(string challengeCode, string clientSecret)
{
    var hmacKeyBytes = Encoding.UTF8.GetBytes(clientSecret);

    using var hmacSha256 = new HMACSHA256(hmacKeyBytes);
    var stringToSignBytes = Encoding.UTF8.GetBytes(challengeCode);
    var signatureBytes = hmacSha256.ComputeHash(stringToSignBytes);
    var signatureHash = Convert.ToBase64String(signatureBytes);
    return signatureHash;
}