Alert Listeners

Tomorrow.io allows you to configure webhooks to receive real-time alerting of the weather events, either based on category or custom insights. It basically allows us to push updates to your application, rather than having your application continually poll for updates.

If you're new to alerts, you can read this guide for more information. You must have predefined alerts that are active and linked to one or more locations, in order to get notifications.

However, remember that notifications are triggered out PRIOR/START/END only when conditions are truthy or as government authorities PUBLISH them. As you test the alerting system, make sure you pick the right locations, such that these thresholds are met.

Testing Webhooks

Before you can begin receiving webhooks, you must configure your Tomorrow.io account with the HTTP endpoints you'd like for the webhooks to be sent to. You can do this through the development page.

You can use a service like requestbin.com or Webhook.site to create temporary URLs to test webhooks which you can then configure in the platform. Any HTTP requests sent to that endpoint will be recorded with the associated payload and headers so you can observe the data sent from our webhooks before coding your application to accept it.

That said, when using Tomorrow.io alerts in a production environment, you will need to provide a more robust web service to host your own custom endpoints. Continue reading to review popular alternatives to creating Alert Listeners, either as a simple web application or using codeless solutions,

Node + Express Webhook Service

This guide walks you through developing a web application that listens for webhook requests, by running a web server and listen for HTTP POST requests on a specified endpoint. This example is written in JavaScript/ NodeJS and uses the Express web framework, and takes into consideration that you're familiar with this environment, have a project and the two are pre-installed.

Import Dependencies
Since all dependencies required for this application are installed, we are ready to import them in the code (in the index.js file) - Express, which is a web framework that provides the web server we are using and which will be configured to use the body-parser package so that we can access the data in the requests sent to the endpoint.

const express = require('express');
const bodyParser = require('body-parser');

Create the Web Application
At this point, we are ready to create our web application and define endpoints. When you configure webhooks in Tomorrow.io, you provide a URL to which we will send an HTTP POST request with a JSON payload according to the notifications setting of active alerts.

The code below creates an instance of an express web server and assigns it to the app variable, configured to use the body-parser package. Then, we create a /notifications endpoint to be used by an "Alerts" notification event webhook. One of the benefits of developing and hosting your own web application is that you can programmatically trigger other events to occur once you receive the webhook. The last line of code starts the server, listening to port 3000 for incoming requests.

const app = express();
app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json());

app.post('/notifications', (req, res) => {

  // handle webhook payload (res.body.data)
  // your code goes here
  
  res.sendStatus(200);
});

let server = app.listen(3000, function() {
  console.log('Listening on port %d', server.address().port);
});

Testing the Web Application
Now that the code logic is ready, let's test it out before we connect it to real webhook requests.
Follow these steps to test that your application is working as expected:

1. Open the index.js in Visual Studio Code, click Run and select "Start Debugging"
2. Download and import the Tomorrow.io Postman Collection
3. Go to the "testers / Test Webhook Listener" endpoint
4. Choose either custom or category based insight by setting the isCustomInsight value
5. Click "Send" to capture the sample payloads

In case you got a successful response from Postman, go back to the VS Code debug console to validate that no unhandled exception was thrown. If there are any errors, fix the express service code before continuing to the next step.

Testing with Real Webhooks
Once the web application is working properly by sending a request to localhost via Postman, without exceptions, you need to make it publicly accessible.

There are several ways to do this for production, but for test purposes, we advise starting off by using ngrok to expose the web application externally, so that Tomorrow.io send messages to the webhook listener:

1. Download and install ngrok
2. Open a terminal and change to the directory where ngrok is installed
3. Run the following command: ngrok http 3000, which forward HTTP traffic to localhost
4. Copy the temporary generate URL shown in the terminal http://[HASH].ngrok.io
5. Follow our Webhooks guide to configure Tomorrow.io to use this URL (and review authentication options)

Note, you'll get a new URL each time you start ngrok, so this won't be a permanent configuration, but it will allow you to test that the web application is receiving and processing Tomorrow.io webhooks as expected.

Deploying to Production
If you reached this point, you should have a validated web service listening to webhooks, and running your own business logic with the payload messages triggered by weather events. Now you will need a more permanent external-facing hosting solution with a cloud provider of your choice (such as AWS, GCP, or Azure).

Other Recommended Integrations

Various third-party services -- like Zapier and IFTTT -- can help you Receive data wthout writing code or running servers. Here's a list of some of our favorite ones:

• Zapier
• IFTTT
• Tray.io
• Slack