Webhooks: Basics and Best Practices
As an engineering team lead at cloudtamer.io, I spend a lot of time thinking over the different use cases for potential integrations with our software. A webhook is one of the tools we use to integrate with different types of infrastructure.
When it comes to governing resources in your cloud, cloudtamer.io can automate a lot of tasks for you. But, what about automation resources outside of your cloud, like JIRA tickets, Slack notifications, and maybe your Raspberry Pi?
cloudtamer.io webhooks are a great way to interact with resources outside of your cloud. Cameron touched on this a bit in his post, Automate Infrastructure with CloudFormation and Webhooks, and we'll go a little deeper here.
What’s a Webhook?
In many applications, you have to build infrastructure that constantly polls the application to determine when data has changed and then trigger actions accordingly. We built webhooks functionality in to act as a notification system between cloudtamer.io and any external applications you want to communicate with. To simplify, here's a scenario. Imagine you are a parent on a road trip with a car full of kids who are waiting for permission to get out. Rather than having the kids ask “are we there yet?” every few minutes (polling method), the kids can sit quietly and wait for the parent to say “we’ve arrived” to signal permission (webhook method) to get out of the car.
Webhooks in cloudtamer.io
When it comes to webhooks, cloudtamer.io has three webhook trigger types: pre-rule, post-rule, and ad hoc. The pre-rule webhook will always trigger before any other actions on a Cloud Rule are applied. Once all actions in a Cloud Rule have executed completely, the post-rule webhook will trigger. A webhook trigger type of ad hoc occurs when you manually trigger the webhook from the UI. Let's look at what information is passed to these webhooks and the best practices for using webhooks in cloudtamer.io.
The examples below reference an internal testing tool that outputs the content of the webhook post, so we know exactly what sort of information we're given and what we can do with it.
When you create a pre-rule webhook, attach it to a Cloud Rule, and then attach to a project, the information passed to the receiving application is specific to each account on the project. This information includes account and project names along with AWS access keys. The access keys are an option you can select when creating your webhook. By default, they're off, but if you're planning on getting into the account and doing some setup work first, they're pretty necessary! Because we know that the EventState is "pre-rule" and that the ActionType (more on this later) is "add", we know for sure that this is happening before a Cloud Rule has started applying. So, whatever prep work we need to do we'll do it now.
Here’s what the testing endpoint shows us when it receives the webhook call. Note that it includes all the fields mentioned:
Next, we’ll look at a post-rule webhook. After the Cloud Rule has finished applying, the post-rule webhook will run and the webhook endpoint will be hit. Because this webhook also has the "post" EventState, we know for sure it's the one that is run after the Cloud Rule has finished applying. We already know at this point: the pre-rule setup ran, the Cloud Rule actions are applied, and we just need to finish up with the post-rule webhook. Need to trigger that Lambda job created in the Cloud Rule after the Cloud Rule is applied? With the access keys being sent, you can again get access to the account(s) and start triggering your jobs there.
Webhooks aren’t only run when applying a Cloud Rule though. While cloudtamer.io does delete the resources created by the Cloud Rule, there might be some resources created by the webhooks that also need addressing. That's where ActionType comes in. The keen-eyed observer will notice this factor in all the webhooks we've run so far. When a Cloud Rule is applied, we'll supply the "add" action type. When deleted, we'll give it the "delete" action type. So when your Cloud Rule is deleted or removed in some fashion, the webhooks will trigger again but this time with an ActionType of "delete". This provides our customers with complete control of setup and teardown such as shutting down environments that cloudtamer.io otherwise doesn't have access to or kicking off Lambda jobs.
This brings us to our last ActionType, the ad hoc action type.
Ad Hoc Webhooks
Ad hoc webhooks can be triggered at any time manually by going to the Webhook page in cloudtamer.io. Click the menu on the right, and click on “Trigger Webhook Manually”. When you trigger a webhook manually, we send the webhook with an ActionType of "adhoc" with whichever EventState was triggered. These are usually used for debugging purposes, or when a webhook needs to be reapplied.
Webhook Best Practices
Make sure your timeouts are set properly. You don't want to set your timeouts too high or too low.
- Too high and you could have a stuck webhook that doesn’t return a completed status, making the rest of your Cloud Rules wait.
- Too low and the webhook might time out before the work is done.
Make sure the receiving endpoint is well tested first! cloudtamer.io will always hit the endpoint during the execution of a Cloud Rule, however the application doesn’t know if the endpoint itself successfully executes its operations. The only indication we have is whether the application times out or if it hits the CallbackURL, so make sure you do some internal testing of the endpoint’s operations before running it in a production environment.
Stay tuned to our release news: we’re making some major updates to webhooks in the first half of 2020, including being able to set the HTTP protocol of the webhook and changing the contents of the JSON in the callout so it will work with almost any application.
Matt is a technical lead at cloudtamer.io.