How to set up a webhook subscription

Overview

This page describes how to set up the Notification Service to call a webhook when a particular resource type is created.

Useful concepts

There are some key concepts related to the Notification Service that will help with understanding this example:

• For a general understanding of how the Notification Service works, refer to the Notification Service overview page.
• For a list of all the system events which the Notification Service can report on, refer to the Notification Service events page.
• For a detailed description of subscriptions using webhooks, refer to the Subscriptions page.

Steps for setting up a webhook subscription

To set up a webhook subscription, do the following:

1. Create a group

2. Create an authorization (optional)

3. Create a subscription

4. Create a trigger

5. Invoke the trigger

Step 1: Create a group

The first step is to create a subscription group.

Groups represent audiences which are interested in specific notifications. For more information on groups, refer to the Groups page.

To create a group, refer to the code example below.

const group = await IafNotification.createGroup({    _namespaces: project._namespaces,    _name: "group_1"}, ctx);

Step 2: Create an authorization (optional)

If required, you can add authorization (authentication) when calling the webhook.

Alternatively, you can skip this step entirely and call the webhook without security credentials.

If using authorization, there are three different types you can use:

• BASIC: HMAC HTTP Basic authorization (username, password)
• HMAC: HMAC based authorization
• API_KEY: A custom secret value added to a user-configurable header

For more details on authorization, refer to the Authorization page.

For this example, we want to create a HMAC authorization. First, create a secret using the Passport Service createSecrets API call.

Then refer to the secret by name when setting up the authorization using the createAuthorization API call.

Refer to the sample code below.

const apiKey = "<my api key>";const secretKey = "<my secret key>";
const secret = await IafPass.createSecrets([{    _name: "TEST_HMAC_SECRET",   _value: secretKey,   _userType: "HMAC_SECRET",    _namespaces: project._namespaces}], ctx);
const authorization = await IafNotification.createAuthorization({    _namespaces: project._namespaces,    _name: "HMAC authorization",    _type: "HMAC",    _hmac: {        _apiKey: apiKey,        _secretKey: {            _name: "TEST_HMAC_SECRET"        }    }}, ctx);

Step 3: Create a subscription

Now we create a webhook subscription to the group.

Before setting up the subscription, you may want to test webhooks. For testing webhooks, you can use an online service such as webhook.site to generate a temporary URL that will log requests.

Note: The _webhook._body property is a Velocity template string, and can contain the same template parameters as available in a template entity.

To create a webhook subcription, refer to trhe sample code below.

const url = "https://webhook.site/<unique id>";
const subscription = await IafNotification.createSubscription({    _namespaces: project._namespaces,    _type: "WEBHOOK",    _group: {        _id: group.id    },    _webhook: {        _method: "POST",        _url: url,        _authorization: {            _id: authorization._id        },        _body: "{\"request\": \"body\"}"    }}, ctx);

Step 4: Create a Trigger

A trigger will match a subscription to incoming events and send notifications when certain events occur.

For a detailed description of triggers, refer to the Triggers page.

To create, an event type trigger, you must indicate the event type we are interested in.

For this example, we will match the creation of new groups within the notification service.

You could also write a filter for entities from other services. For more information about other entity types and other services, refer to the Notification Service events page.

In this example, we want to specify the event filter we will use to listen to events created in the Notification Service for the current project namespace.

Refer to the sample code below.

{  "event", "resource.ResourceCreated",  "resource.type", "notificationsvc.Group",  "resource.namespaces", project._namespaces}

Note: The event type is ResourceCreated, the resource type is Group and the resource namespaces are those of the current project. A filter for resource.namespaces must always be included, and will be validated against the owning namespace of the trigger.

We also want to reference the group we have just created. For this example we do not need to create templates or senders, although a trigger could refer to groups that contain a mixture of webhook and device subscriptions.

In the example, we want to reference senders and templates to match the transport types.

Refer to the sample code below.

const trigger = await IafNotification.createTrigger{    _namespaces: project._namespaces,    _type: "EVENT",    _event: {        _filters: {            "event", "resource.ResourceCreated",          "resource.type", "notificationsvc.Group",          "resource.namespaces", project._namespaces        }    },    _groups: [        {            _id: group.id        }       ]}, ctx);

Step 5: Invoke the trigger

In this final step, we will create any new groups in our namespace. This causes the trigger to be matched, and the webhook will be invoked.

Refer to the sample code below.

const triggeringGroup = await IafNotification.createGroup({    _namespaces: project._namespaces,    _name: "group_2"}, ctx);