Webhook

Definition

A private webhook plugin contains user-defined logic that is triggered by 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, follows the file structure shown below:

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

control

This is a script written in either Python or NodeJS. Think of it as a setup script, since it runs only once when the plugin is created.

function

This is a script written in either Python or NodeJS. It contains the plugin's core logic and 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 needed, the plugin developer can let users execute custom logic. This script gives users 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 let users further process or redirect that data without altering the core logic.

The user_code script provides that flexibility. It preserves the plugin's encapsulation while offering a dedicated space for user-specific logic.

Naming convention

You must use the names of all files and directories listed in the "Required files" section, since the plugins engine specifically looks for these files and their extensions.

For instance:

• If your plugin uses Python as its runtime, the script names should be control.py, function.py, and user_code.py

• If your plugin uses NodeJS as its runtime, the script names should be control.js, function.js, and user_code.js

The language selected for the control, function, and user_code scripts must match the value of the runtime key in the manifest.toml file.

view.xml

This file lets the developer build and display a form that users can use to enter the parameters required by the plugin.

The contents of this form are displayed in the plugin creation modal.

For example, if we create a plugin to receive data from an LNS during device uplinks, we would need the user's LNS and Ubidots credentials. A GUI for this plugin could look like this:

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 form parameters are accessible to the function, control, and user_code scripts on each execution through the _parameters key in the incoming JSON object.

For detailed information about the supported elements in the view.xml file, refer to its dedicated section in the Plugins development page.

LICENSE and README.md files

Refer to the Private Plugins page for more information:

Private plugins

Manifest.toml

Aside from the manifest components common to all plugin types, the following are specific to webhook plugins:

Section	Key	Value	Description	Example
[settings]	runtime	Any valid 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 this:

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 keys are mandatory.