Home

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 word "echo" 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:

WebHookUri Required The URI of the WebHook listener.
Secret Required A secret key which is used to sign the HTTP POST request.
Filters Required Case-insensitive filters associated with this WebHook.The filters indicate which WebHook events that this WebHook will be notified for. The list of filters can be obtained from /api/webhooks/filters.
IsPaused Optional A value indicating whether the WebHook is paused. By default is set to false.
Description Optional Some description of the WebHook.

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:

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.