Webhooks

The HelloFlex REST APIs use webhooks for event notification.

Overview

Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook in HelloFlex API, you need to configure a webhook listener and subscribe it to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. HelloFlex signs each notification message that it delivers to your webhook listener.

Integration steps

To configure your webhook listener to receive notification messages for events:

1. Configure a webhook listener

2. Registers to events

3. Verify event notifications

Configure a webhook listener

A webhook listener is a server that listens at a specific URL for incoming HTTP requests. After you configure a listener, note the URL for the listener. You need this URL to subscribe your webhook listener to events.

The URL should follow the pattern: {protocol}://{host}/{receiver}

For security reasons, many WebHook receivers require that the URI is an https URI and in some cases it must also contain an additional query parameter which is used to enforce that only the intended party can send WebHooks to the URI above. The component is the name of the receiver(consumer)

A webhook listener have to support GET and POST HTTP methods for incoming WebHook request at the same URL endpoint:

• GET is typically used to verify that a WebHook is correctly wired up. When you create a new webhook, we'll send you a simple ping event to let you know you've set up the webhook correctly. You need to prepare a response body with the received request "echo" query parameter value and status code 200 Ok

• The POST is the actual WebHook notification messages that are triggered when events occur.

Registers to events

Before registering, your webhook listener must be working and accept HTTP GET and POST requests

When you register your listener to events, you define:

Important: Webhooks are asynchronous, their order is not guaranteed, and idempotency might lead to a duplicate notification of the same event type.

To subscribe your webhook listener to events:

1. Get access_token from /oauth2/token.

2. Prepare a new POST request to api/webhooks/registrations.

3. Add Authorization header with access_token like Authorization: Bearer access_token.

4. Specify Content-Type: application/json.

5. Add body of request like:

   {
   	"WebHookUri": "http://example.com/api/incoming",
   	"Secret": "string",
   	"description": "string",
   	"isPaused": false,
   	"filters": [
   		"filterName1", "filterName2", ..., "filterNameN"
   	]
   }

   Note: The list of filters name can be obtained from /api/webhooks/filters. Use "*" to subscribe on all events.

6. Send request.

If registration is successful then response should be something like this:

status: 201
content-type: application/json; charset=utf-8
location: api/webhooks/registrations/guid_of_webhook
{"id":"guid_of_webhook","webHookUri":"listener_url","secret":"your_secret","description":"webhook_description","isPaused":false,"filters":[array of filters name],"headers":{},"properties":{}}  

You can use this webhook ID to complete these Webhooks API operations:

• Show webhook details
• List all webhooks
• Update webhook
• Delete webhook

Also, response includes ms-signature header with HMAC hex digest of the response body. This header will be sent if the webhook is configured with a Secret. The HMAC hex digest is generated using the sha256 hash function and the Secret as the HMAC key.

Verify event notifications

You can verify webhook event notifications that your listener receives when events occur.

Each POST webhook request includes a ms-signature header which is generated using the app's shared secret, along with the data sent in the request.

Example: ms-signature: sha256=6B3E052D2ED0890700A8315ED53AE9E469219619BFFC34778324F936C5FC4B9A

To verify that the request came from HelloFlex, compute the HMAC digest according to the following algorithm and compare it to the value in the ms-signature header (except sha256=). If they match, you can be sure that the Webhook was sent from HelloFlex and the data has not been compromised.

Below is a simple example in C# using the ASP.NET WebAPI of how one might receive and verify a webhook request.

using Newtonsoft.Json.Linq;
using System;
using System.Collections.Specialized;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using System.Web.Http;

/// <summary>
/// Accepts incoming WebHook requests and process them.
/// </summary>
[RoutePrefix("api/incoming")]
public class WebHookController : ApiController
{
	/// <summary>
	/// Supports GET for incoming WebHook request. This is typically used to verify that a WebHook is correctly wired up.
	/// </summary>
	[Route("{webHookReceiver}")]
	[AllowAnonymous]
	public IHttpActionResult Get(string webHookReceiver)
	{
		// Return the echo response
		NameValueCollection queryParameters = Request.RequestUri.ParseQueryString();
		string echo = queryParameters["echo"];
		HttpResponseMessage echoResponse = Request.CreateResponse();
		echoResponse.Content = new StringContent(echo);
		return ResponseMessage(echoResponse);
	}

	/// <summary>
	/// Supports POST for incoming WebHook requests. This is typically the actual WebHook.
	/// </summary>
	[Route("{webHookReceiver}/{id?}")]
	[AllowAnonymous]
	public async Task<IHttpActionResult>Post(string webHookReceiver, string id = "")
	{
		HttpResponseMessage response = new HttpResponseMessage();

		if (RequestContext == null)
		{
		throw new ArgumentNullException(nameof(RequestContext));
		}

		if (Request == null)
		{
		throw new ArgumentNullException(nameof(Request));
		}

		if (Request.Method == HttpMethod.Post)
		{
		await VerifySignature(Request);

		// Read the request entity body
		JObject data = await Request.Content.ReadAsAsync<JObject>();
		// TODO: process webhook data
		}
		return ResponseMessage(response); // --> ok
	}

	private async Task VerifySignature(HttpRequestMessage request)
	{
		const string secretKey = "12345678901234567890123456789012";
		const string signatureHeaderName = "ms-signature";

		// Get the expected hash from the signature header
		if (request.Headers.TryGetValues(signatureHeaderName, out var headers))
		{
			string headerValue = headers.First().Replace("sha256=", "");

			byte[] expectedHash;
			try
			{
				expectedHash = FromHex(headerValue);
			}
			catch (Exception)
			{
				var invalidEncoding = request.CreateErrorResponse(HttpStatusCode.BadRequest, $"The '{headerValue}' header value is invalid. It must be a valid hex-encoded string.");
				throw new HttpResponseException(invalidEncoding);
			}

			// Compute the actual hash of the request body
			byte[] actualHash;
			var secret = Encoding.UTF8.GetBytes(secretKey);
			using (var hasher = new HMACSHA256(secret))
			{
				var data = await request.Content.ReadAsByteArrayAsync();
				actualHash = hasher.ComputeHash(data);
			}

			// Now verify that the actual hash matches the expected hash.
			if (!SecretEqual(expectedHash, actualHash))
			{
				var message = $"The WebHook signature provided by the '{signatureHeaderName}' header field does not match the value expected by the receiver. WebHook request is invalid.";
				var badSignature = request.CreateErrorResponse(HttpStatusCode.BadRequest, message);
				throw new HttpResponseException(badSignature);
			}
		}
	}

	private static bool SecretEqual(byte[] inputA, byte[] inputB)
	{
		if (ReferenceEquals(inputA, inputB))
		{
			return true;
		}

		if (inputA == null || inputB == null || inputA.Length != inputB.Length)
		{
			return false;
		}

		var areSame = true;
		for (var i = 0; i < inputA.Length; i++)
		{
			areSame &= inputA[i] == inputB[i];
		}
		return areSame;
	}

	private static byte[] FromHex(string content)
	{
		if (string.IsNullOrEmpty(content))
		{
			return new byte[0];
		}

		byte[] data;
		try
		{
			data = new byte[content.Length / 2];
			var input = 0;
			for (var output = 0; output < data.Length; output++)
			{
				data[output] = Convert.ToByte(new string(new[] { content[input++], content[input++] }), 16);
			}

			if (input != content.Length)
			{
				data = null;
			}
		}
		catch
		{
			data = null;
		}

		if (data == null)
		{
			throw new InvalidOperationException($"Input is not a valid hex-encoded string: '{content}'. Please provide a valid hex-encoded string.");
		}
		return data;
	}
}