# pelion-aws-lambda-webhook-example **Repository Path**: mirrors_ARMmbed/pelion-aws-lambda-webhook-example ## Basic Information - **Project Name**: pelion-aws-lambda-webhook-example - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-23 - **Last Updated**: 2025-09-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Pelion Webhook Example ## Overview Pelion Device Management is a powerful solution for connecting and managing IoT devices securely and efficiently. IoT devices running the Pelion Device Management Client connect to the Pelion service to be monitored and updated. The Pelion service provides APIs for authenticated access to data from your connected device fleets. This example shows how to set up a webhook notification channel and subscribe to specific resources from devices. When a resource (e.g. counter value) gets updated on a device in your fleet, a notification message gets sent through the webhook to a web application. In this case the web application is an AWS Lambda function which passes data to Elasticsearch. This is used to collect, store, and graph the data. For more information, check out the Pelion documentation pages on [collecting data from devices](https://www.pelion.com/docs/device-management/current/integrate-web-app/event-notification.html) and [service APIs](https://developer.pelion.com/docs/device-management/current/service-api-references/index.html). ## Details The following example implements a callback handler for a Pelion [event notification channel](https://www.pelion.com/docs/device-management/current/integrate-web-app/event-notification.html) using Amazon AWS [API Gateway](https://aws.amazon.com/api-gateway/) and [Lambda](https://aws.amazon.com/lambda/). Notifications and device registration messages are parsed and sent to [Elasticsearch](https://aws.amazon.com/elasticsearch-service/) for storage. Queries and visualization are done with Kibana. ![Block Diagram](/images/block-diagram.png) # Installation ## Prerequisites - AWS account with access to: - API Gateway. - Lambda. - CloudWatch (for logging). - IAM (for creating roles). - Elasticsearch. - Pelion account with access to an Application Access key. - Command terminal with access to Curl. - A device running Pelion Device Management Client that is connected and registered to Pelion (For example, a device running the Pelion example application at [mbed-os-example-pelion](https://github.com/armmbed/mbed-os-example-pelion)) ## Setup Before setting up the notification channel, first configure the AWS components. - First, login to the [AWS Management Console](http://console.aws.amazon.com). ### AWS CloudWatch Access - Follow [this guide](https://aws.amazon.com/premiumsupport/knowledge-center/api-gateway-cloudwatch-logs/) to enable CloudWatch logging from API Gateway. This will enable logs that can be useful when debugging issues. ### AWS Elasticsearch - In the AWS console, search for **Elasticsearch** and open the Elasticsearch service dashboard. - Click **Create a new domain**. Choose these settings: - Deployment type - Deployment type: Development and testing - Elasticsearch Version: 7.9 or greater *(note that it has only been tested with 7.9)* - Configure Domain - Elasticsearch domain name: *Any name you choose (e.g. pelion-data)* - Instance type: t2.small.elasticsearch - Number of nodes: 1 - Data nodes storage type: EBS - EBS volume type: General Purpose (SSD) - EBS volume size: 10 GiB - Configure access and security - Public access: Enabled - Domain access policy: Allow open access to the domain - Require HTTPS: Enabled Notes: - Features not specifically mentioned can be disabled. - For testing purposes, the smallest cluster setting should be sufficient. Note that this still may not be covered by the AWS free tier, but the cost should be minimal. - For convenience in setting up this example for demonstration and testing purposes, *open access* is enabled. Note that anyone with the autogenerated URL (including the Lambda function) will have permission to read and write to this instance. For production, configure and use an appropriate AWS Virtual Private Cloud (VPC). Configure Elasticsearch and Kibana to received data: - Take a note of the URLs labled **Endpoint** and **Kibana**. The endpoint URL will be used by the Lambda function for data insertion and the Kibana URL will be used for visualizing data. - Open the Kibana URL, click on the menu, and go to the **Dev Tools**. - In the console UI, paste the following commands one at a time and pressing the icon to **Click and send request**. This will create three new indexes and tell Elasticsearch how to interpret the received messages. #### Notifications index ``` PUT /notifications { "mappings" : { "properties" : { "time" : { "type" : "date" }, "endpoint" : { "type" : "text" }, "path" : { "type" : "text" }, "value" : { "type" : "double" } } } } ``` #### Device information index ``` PUT /devices { "mappings" : { "properties" : { "time" : { "type" : "date" }, "endpoint" : { "type" : "text" }, "original-ep" : { "type" : "text" }, "ept" : { "type" : "text" }, "resources" : { "type" : "text" } } } } ``` #### Device registration index ``` PUT /registrations { "mappings" : { "properties" : { "time" : { "type" : "date" }, "endpoint" : { "type" : "text" }, "value" : { "type" : "integer" } } } } ``` ### AWS Lambda - Search for and open the **Lambda** dashboard. - Choose **Create Function** and **Author From Scratch**. - Pick a suitable function name (e.g. pass_pelion_data) - Choose at least Node.js 12.x - Select *Create a new role with basic Lambda permissions* or *Use an existing role* if you already have one. - Click **Create Function** - Copy the contents of `index.js` from this repository into the file named `index.js` within the Lambda Function code workspace. - Create a new file in the Lambda workspace named `elasticsearch.js` and copy the contents from the file `elasticsearch.js` from this repository into it. - Under *Runtime settings*, ensure the field **Handler** is set to **index.handler**. - Under **Environment Variables**, create a new variable `ELASTICSEARCH_DOMAIN` with the Elasticsearch *Endpoint* name from earlier without the "https://". - Under **Basic Settings**, ensure the default 128 MiB RAM and 3 second timeout are set. This should be sufficient for testing. - At the top, under **Designer**, click the **Add Trigger** template and choose **API Gateway**. ### AWS API Gateway - In the **Add trigger** template, choose **Create an API** then select **REST API**. - Under *Security*, choose **API key** - Enable logging. Note, this may fail due to missing permissions. Follow the guide above about CloudWatch roles and try again. - Note the **API Endpoint** URL and the **API key**. ### Pelion Cloud REST API Now that your AWS account is configured to receive notification messages, you must configure Pelion to generate and send the messages to the right place. This is done by setting up a callback URL and subscribing to specific resources in your Pelion account. Once this is completed, the messages will start to flow. In this section, we will use *cURL* to send *HTTPS* commands to configure our Pelion account. Alternatively, you could use other tools or software libraries to do the job. - Log in to the [Pelion Device Management portal](https://portal.mbedcloud.com/login). - Follow [this guide](https://developer.pelion.com/docs/device-management/current/user-account/application-access-keys.html) to create a new application access key. - From a command terminal execute: ``` curl -X PUT https://api.us-east-1.mbedcloud.com/v2/notification/callback \ -H 'Authorization: Bearer PELION_API_KEY' \ -H 'content-type: application/json' \ -d '{ "url": "AWS_API_ENDPOINT", "headers": { "x-api-key": "AWS_API_KEY"} }' ``` Where `PELION_API_KEY` is the access key from Pelion Device Management portal, `AWS_API_ENDPOINT` and `AWS_API_KEY` are the API endpoint and key retrieved from AWS API Gateway earlier. If all goes well, you should get a **204** response back. - Next, enable pre-subscriptions for LwM2M resources that you want to be sent to Elasticsearch. Subscriptions and pre-subscription can be managed with the [v2/subscriptions](https://developer.pelion.com/docs/device-management-api/connect/#/Device%20data%20-%20subscriptions) REST API endpoint on Pelion. Replace `/object/instance/resource` with a resource that your device application has enabled for GET operations. For example, if your devices are running the [mbed-os-example-application](https://github.com/armmbed/mbed-os-example-pelion), then you can use **3200/0/5501**, which is a digital counter that updates once a second. ``` curl -X PUT https://api.us-east-1.mbedcloud.com/v2/subscriptions \ -H 'Authorization: Bearer PELION_API_KEY' \ -H 'content-type: application/json' \ -d '[ { "endpoint-name": "*", "resource-path": ["/object/instance/resource", ... ] } ]' ``` If successful, you should get a **204** response back. For more information about service APIs check out the [notifications](https://developer.pelion.com/docs/device-management-api/notifications) and [connect](https://developer.pelion.com/docs/device-management-api/connect/) documentation pages. ### AWS Kibana In the preceeding steps, we configured Pelion to send device notifications to AWS Elasticsearch through AWS API Gateway and Lambda services. Now, whenever a device connected to Pelion Device Management updates a pre-subscribed LwM2M resource, it sends the numerical data within a notification message to Elasticsearch. Kibana is a data visualization dashboard that comes with Elasticsearch where the data can be viewed. - Open the Kibana URL, click on the menu, and go to **Stack Management** and click on **Index Patterns** - Click **Create index pattern**. In the *index pattern name* textbox, type the name of one of the previously created indices followed by an asterick (e.g. devices*). Click **Next step**. - For the *Time field* select **time**, then click **Create index pattern**. - Repeat the previous steps to create three new index patterns - one for each index: *notifications*, *devices*, *registrations*. Congratulations. If everything went well, raw data can now be accessed under the Kibana menu **Discover**. - Select the index pattern you want to view and set an appropriate time range, which data should be available (e.g. Last 15 minutes). Graphs can be created under Kibana menu **Visualize**. - For example, select **Create visualization**, then choose **Line** graph. Select index pattern **notifications**. For the *Y-axis* choose an *aggregation* such as **Max**. For the *field* select **value**. Under *Buckets*, click **Add**, and select **X-axis**. Then for the *aggregation* choose **Date Histogram** and under *field* select **time**. Click **Update**. - Select an appropriate date range for your data and click **Refresh**. You should now see a line graph of the resource values provided by your device! ![Kibana Graph Example](/images/kibana.png) Best of luck with your next project!