Device to Cloud Getting Started Integrate your application via HTTP webhook

Introduction

This chapter describes how you can integrate your application using an HTTP webhook with D2C, so that it can be used as an endpoint for the uplink message routing.

If your application’s HTTP webhook is not readily available for initial testing with D2C, this Get Started guide will help you temporarily use a test API endpoint at webhook.site .

The following three steps will guide you through your first integration of an HTTP webhook as a D2C application:

  1. Create simple webhook at webhook.site
  2. Register your webhook as application in D2C
  3. Verify your webhook

Create simple webhook at webhook.site

In case you don’t have a webhook URL of your own application available, you can create a test webhook endpoint by simply opening the website https://webhook.site .

https://webhook.site

https://webhook.site
If you open [https://webhook.site](https://webhook.site) in your browser, a unique temporary webhook URL is created automatically. Keep the browser window open to see the messages sent from **D2C** to this webhook. We will use this webhook to create a **D2C** webhook application.

To copy the webhook URL, simply click on it (e.g., https://webhook.site/831255b2-7e62-4608-90d6-58d7a9292e1C in the example above), and it will be copied to your clipboard.

Register your webhook as application in D2C

To allow D2C to send uplink messages from devices to your application using a webhook, you need to create a WebHook Application in D2C.

Go to the Applications tab in D2C, click the Add application button, and choose the WebHook option. This will open a dialog where you can set up your WebHook Application.

D2C application tab

D2C application tab

Add webhook application dialog

Add webhook application dialog
In the *Add application* dialog, enter a unique *Name* for your application and the *Callback URL* of your webhook. For initial tests using a webhook from [webhook.site](https://webhook.site), you do not need to add any extra *Header Fields*.
⚠️
In early versions of D2C, the Add application dialog may include an automatically created empty header field. If you do not assign a name and value to this header field, you must delete it manually. Otherwise, an error will occur when trying to create the application.

After clicking the Add application button in the dialog, the Application object and a corresponding default Device Group with the same name is created in D2C. Next, close the confirmation window and refresh the Applications tab in your browser. You will see both at the top of the list of objects in the Applications tab (see figure below).

Newly created application with its default Device Group

Newly created application with its default Device Group
👉 URL VERIFICATION
If D2C creates or updates a WebHook Application, it tests if the URL of the WebHook Application exists and accepts HTTP POST requests. To do so it sends a POST request with an empty body and expects an OK HTTP response code such as 200 or 202.
👉 IMPORTANT CONVENTION
From the system perspective it is possible to name an Application and an unrelated Device Group object the same. BUT, you shouldn’t do this. It is a D2C convention to assign an application to a device group if both have the same name.

Verify your webhook

To check if D2C can send messages to your previously created Webhook Application, you need a Device object. Simply assign this Device object to the default Device Group which has been automatically created for the Application before.

⚠️
Before you assign your Device to the Device Group of your Application, make sure your browser shows the webhook site you have opened before, and where you have copied the webhook URL to the Application object from.

To assign the Device to the Device Group go to the Applications tab and select the Edit devices function in the context menu of the Application’s’ Device Group (see figure below).

Device group context menu

Device group context menu
On the *Edit device assignments* page, select your device using the checkbox on the left side, and click the *Update group* button at the top right corner (see figure below.)

Edit device assignment of a device group

Edit device assignment of a device group
For every *Device* you assign to a *Device Group*, **D2C** sends a *oneM2M Signal** to inform the *Application* linked to the *Device Group* about a device subscription.
{
    "m2m:sgn": {
        "sur": "d2c-wbv/68ac89661b8ac79b38673a6b",
        "vrq": true,
        "cr": "CAdmin"
    }
}

Element nameTypeDescription
m2m:sgnoneM2M typeSignal or subscription notification
surstringSubscription resource name
vrqbooleanVerification request. If set to true it shall be checked if the application is still reachable. If the application URL is not reachable, times out or returns a HTTP response code other than OK (2xx), and the subscription is NOT created.
crstring.oneM2M id of the signal originator

⚠️ IMPORTANT
If your webhook doesn’t return HTTP OK (2xx) the subscription for the Device is NOT created, and uplink messages of the Device are NOT forwarded to your webhook.

If everything is set up correctly, you should see the oneM2M Signal in the webhook.site page that you have kept open during this tutorial (see figure below).

Webhook site after receiving the oneM2M subscription notification

Webhook site after receiving the oneM2M subscription notification
----
➡️ NEXT