Node-RED webhooks without public IP

What is Node RED?

Node-RED is a visual programming tool that helps people connect and automate devices, services, and data in a simple and visual way. It’s like a digital flowchart where you can create and link “nodes” to make things happen, such as turning on lights when you receive an email or collecting data from sensors and sending it to a database. Node-RED makes it easier for non-programmers to build custom automation and data-processing tasks without writing complex code.

Use case

Webhook Relay websockets let devices to receive webhooks by popular services such as IFTTT, Zapier or anything else without having a public IP. It can also be used for remote access if you are using tunnels. Since webhooks are just a standard HTTP requests, any services can easily produce and consume them. Webhook Relay is particularly useful when:

  • Your IoT devices can’t run an HTTP web server to receive webhooks
  • You don’t want to run a public MQTT server
  • You cannot access your router to configure port forwarding
  • Router doesn’t support port forwarding
  • Your ISP blocks inbound connections
  • You don’t have a static IP address
  • Server that is hosting your home automation system is changing IP, location

Node-RED

Node-RED is a programming tool for wiring together hardware devices, APIs and online services in new and interesting ways. It provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes in the palette that can be deployed to its runtime in a single-click.

We provide node-red-contrib-webhookrelay node that can be used with Node-RED to easily received webhooks.

Usage

To use this node, some configuration is required:

  1. Install node-red-contrib-webhookrelay
  2. Create bucket at https://my.webhookrelay.com/buckets
  3. Generate tokens at https://my.webhookrelay.com/tokens
  4. Supply bucket and token key & secret into the node

Detailed steps with screenshots are available below.

Installing node-red-contrib-webhookrelay node

Open ‘palette’ on your Node-RED web interface and install node-red-contrib-webhookrelay node:

install node-red-contrib-webhookrelay node

Creating Webhook Relay bucket

Buckets are like groups where you can have multiple input URLs and multiple outputs. Since we are using WebSocket streaming, we don’t really care about the outputs. However, it’s good to create at least one output since then you will be able to resend webhooks manually (good for testing integrations).

Go to your buckets page and create a bucket called nodered:

bucket created

Getting token key & secret

Retrieve token key & secret from https://my.webhookrelay.com/tokens page. While token key will remain visible, secret is already encrypted and cannot be decrypted. If you lose your secret, just delete the token and create a new one.

Configuring node-red-contrib-webhookrelay node

Add bucket name and your token key & secret into the node:

configuring webhookrelay node

Receiving webhooks

Any HTTP requests that are received by your Wehbook Relay bucket will be sent to your Node-RED instance:

webhook received

Message structure

Message contains several fields:

  • topic - bucket name so you can easily use switches if you have multiple buckets streaming at once.
  • payload - actual JSON object with all request information:
{
    "topic": "nodered",
    "payload": {
        "type": "webhook",
        "meta": {
            "bucked_id": "12302faf-43bd-43c4-ab1d-89a8b0505693",
            "bucket_name": "nodered",
            "input_id": "544a6fe8-83fe-4361-a264-0fd486e1665d",
            "input_name": "Default public endpoint",
            "output_name": "",
            "output_destination": ""
        },
        "headers": {
            "Content-Type": ["application/json"],
            "Accept": ["*/*"],
            "Content-Length": ["29"],            
        },
        "query": "",
        "body": "{\n\t\"msg\": \"hello Node-RED!\"\n}",
        "method": "PUT"
    },
    "_msgid": "eb4a7330.c838b"
}

Responding to webhooks

Webhook Relay allows responding to webhooks via Node-RED from 0.3.0 version. To send responses, ensure that your bucket’s input is configured to return responses (by default for security reasons it will always return 200 status code and an empty body):

  1. Go to your buckets page https://my.webhookrelay.com/buckets
  2. Go to the bucket details
  3. Go to the input details (click CONFIGURE)
  4. From the ‘Response configuration’ section click on a ‘Dynamic response from output’ dropdown and select “Any output”

select response

Now, to send back responses from the Node-RED back to Webhook Relay so it can respond to the caller, form a payload:

return {
    meta: msg.payload.meta,  // this is original meta field from the payload (it's important to include it so we have the message ID)
    status: 200, // status code to return (200, 201, 400, etc)
    body: "any payload here (if you want to send JSON, just stringify it first)", // body
    headers: {
      someheader: ['somevalue']
    } 
};

A simple flow that just responds to requests, looks like:

func response flow

Then, send this payload back to the Webhook Relay node through its input:

$ curl https://my.webhookrelay.com/v1/webhooks/d00e0b31-438f-454f-ab5e-406215aeef84
any payload here (if you want to send JSON, just stringify it first)

Reporting issues

If you encounter any issues or requests, either submit them here or on the github repository here https://github.com/webhookrelay/node-red-contrib-webhookrelay.