Webhook

Definition

A private webhook plugin is a user-defined logic whose executions is triggered by making an HTTP request to its HTTPS Endpoint URL:

Required files

As stated before any Private plugin regardless of its type, and, particularly, a private webhook plugin, is composed by the file structure shown below:

├── src
│   ├── control     
│   ├── function
│   ├── user_code
│   ├── view.xml
├── LICENSE
├── README.md
├── manifest.toml

control

This is a script, written either in Python or NodeJS. This can be thought as a "setup" script since it will run only once at the moment of creating the plugin.

function

This is written in either Python or NodeJS, and it holds the plugin's core logic. The script runs every time an HTTP request is made to the plugin's HTTPS Endpoint URL.

user_code

This is written either in Python or NodeJS.

If required, the plugin's developer can opt to offer its users a way to execute custom logic. Thus, this script empowers the user with an additional level of customization.

For instance, if a developer creates a webhook plugin to fetch data from an external API, they might want to allow users to further process or redirect that data without altering the core logic.

The user_code script provides this flexibility, maintaining the plugin's encapsulation while offering a dedicated space for user-specific logic.

Naming convention

You ought to retain the names of all files and directories mentioned in the "required files" section, as the plugins engine specifically searches for these files and their extensions.

For instance:

• If your plugin is using Python as runtime, the scripts' names should be control.py, function.py and user_code.py

• If your plugin is using NodeJS as runtime, the scripts' names should be control.js, function.js and user_code.js

The language selected for the control, functionand user_codescripts must match with the value of theruntime key in the manifest.toml file

view.xml

This file provides the developer with the capability of building and displaying a form, so the plugin's users can use it to input the required parameters by it

The contents of this form are displayed when the plugin is about to be created.

For instance, if creating a plugin to receive data from an LNS during device uplinks, you'd need the user's LNS and Ubidots credentials. A GUI for this widget might look like:

This can be achieved using text fields in the form as shown below:

<form name="formName">

    <group name="ttitenantInformation">
        <group name="ttinetworkTenant">
            <label name="tti-tenant-label" help="If you have a TTI Dedicated Cloud license, you can find the Tenant ID as the first portion of your account access URL. [https://www.thethingsindustries.com/docs/getting-started/cloud-hosted/addresses/](Learn more)">TTI Tenant ID</label>
            <input name="tti-tenant" type="text" value="tti"/>
        </group>
    </group>
    
     <group name="group2">
        <group name="ttiapiInformation">
            <label name="tti-api-label" help="A TTS API key with enough permissions to view and list gateways. [https://help.ubidots.com/en/articles/4824641-plugins-monitor-your-tts-lorawan-gateways-with-ubidots](Learn more).">TTI API Key</label>
            <input name="tti-api-key" type="password"/>
        </group>
    </group>

    <group name="ubidotsInformation">
        <group name="fieldToken">
            <label name="labelToken">Ubidots Token</label>
            <token name="token" placeholder="Select Token"/>
        </group>
    </group>

</form>

All of these parameters in the form are accessible to the function, control and user_code scripts on each of its executions within the _parameters key in the incoming JSON object.

For detailed information about the supported form elements, please head to the view.xml section in the Plugins development page:

view.xml

LICENSE and README.md files

Refer to Private Plugins page to get more information:

Private Plugins

Manifest.toml

Aside from the manifest components common to all plugin types, the following ones are specific to Webhook type plugin:

Section	key	Value	Description	Example
[settings]	runtime	Any valir Python or NodeJS version	Environment in which the plugin will run	runtime = "python:3.7"
[settings.webhook]	default_http_method	A valid HTTP method	Default HTTP method to be used by the plugin	default_http_method = "POST"
[settings.webhook]	allowed_http_methods	A list of valid HTTP methods	HTTP methods allowed by the plugin	allowed_http_methods = ["POST"]

With that in mind, a typical manifest.toml file for a Private Webhook plugin looks like:

manifest_version = 2.0
 
[settings] 
version = "1.0.56" 
runtime = "python:3.7" 
plugin_type = "webhook" 
license_name = "MIT license" 

[settings.webhook]
default_http_method = "POST"
allowed_http_methods =  ["POST"]

All of these manifest's keys are mandatory