May 10

Tutorial: Setting Up a Webhook Endpoint

AerisWeather’s Webhooks provide timely notifications of the weather events that you care about most. Eliminate the need for continuous polling, along with the need to worry about missing critical alerts. Webhooks deliver all of your weather events – whether it be lightning, approaching storms, or other – rapidly and directly right to you. In this webhook tutorial, we’ll cover setting up your own webhook endpoint from scratch on Amazon Web Services (AWS). We’ll also go over some best practices to help you get the most out of Webhooks.

Before Getting Started

There are some things you should know before going through this tutorial.

First, creating resources on AWS may incur charges. If you’re following this tutorial closely, your utilization should fall within the AWS “free tier” for Lambda and API Gateway. If you have maxed out free tier utilization, the resulting charges should be no more than a few cents. That said, AerisWeather cannot be responsible for the cost incurred by following this tutorial. You may wish to configure a budget within AWS to notify you if your monthly spending surpasses a certain threshold.

Second, the tutorial repository provides supplemental content to get your webhook demo endpoint up and running quickly. To that end, we cover only the absolute necessities to configure a webhook endpoint. This tutorial is not intended for direct deployment into a production environment.

Webhook Tutorial Prerequisites

With that out of the way, here is what you will need to follow along with this tutorial:

Once the prerequisites are met, it’s time to deploy the infrastructure!

Deploying the Infrastructure

In the tutorial repository, change into the directory and run . Terraform will create a Lambda function and API Gateway in AWS to serve as a demo webhook endpoint.

Heads up! You will want to run in the directory when you are all done with this demo. That will ensure the demo resources are destroyed and that you will not be billed for them. You can recreate them at any time!

When Terraform finishes, it will print out the URL to your demo webhook endpoint. It will look something like this:

Now you’re ready to start making requests.

Make a Test Request

You can make a test request against your endpoint by running the script in the tutorial repository:

This will post the contents of the file to the endpoint. With the demo code in this repository, you should see:

This response has come from the webhook endpoint that you deployed. The code that powers the endpoint is in .

There are a couple of other test data files in the directory. Try posting those and see what happens!

Exercise: Modify webhook.py

The current webhook endpoint code takes a data payload in the form returned by the Aeris API (as AerisWeather Webhooks will provide) and determines what types of alerts are contained within.

Modify so that it returns the name of the place where the alert is issued, instead.

To test locally, you can run

to simulate POSTing to the webhook endpoint. It doesn’t actually POST anything anywhere; it just runs the script in a different mode.

When you want to publish your changes to the webhook endpoint, change into the directory and run again. After you publish the changes, you will be able to run

to send the data to your live webhook endpoint.

Recap

In this tutorial, you learned how to deploy a webhook endpoint powered by Lambda and API Gateway using Terraform. You performed some basic processing on POSTed alerts and returned a response.

Next Steps

To build out your own webhook endpoint, check out the definitions in as a starting point. There are many ways to provide a webhook endpoint service — the way we suggested here is easy and cheap for low-volume services.

You may also wish to take the example script provided here and convert it to another language supported by Lambda.

When you feel like you have a solid grasp on configuring a webhook endpoint, check out the list of best practices below.

Don’t forget to clean up the infrastructure you deployed by running in the directory when you are finished!

Best Practices

For the best experience with AerisWeather Webhooks, make sure your endpoint adheres to the best practices outlined here. Ensure that your webhook endpoint…

  • …returns an appropriate HTTP status code.
    • 200, 202, 204 status codes indicate success (with some minor differences).
    • 400 indicates that the request format wasn’t what you expected.
    • 401 indicates that API key provided to your endpoint was incorrect (i.e.
      authentication failed)
    • 500 indicates that your service experienced an internal error that it could
      not handle.
  • …returns a response quickly. Do not perform slow processing on weather
    events immediately when they hit your endpoint. Instead, store the events
    somewhere and process them via another mechanism.
  • …is available most of the time. While AerisWeather Webhooks will retry if
    your service encounters an error, we will not perform retries forever!

We hope you found our webhook tutorial helpful. If you haven’t already, start your free 30-day AerisWeather developer trial here, and if you have any questions, feel free to consult our documentation or reach out to our Support Team. Happy coding!

For more information on Webhooks, check out these other resources: 

Share this post:

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.