Software platforms like Beanstalk offer a lot of functionality right from the start. But as the world of SaaS (Software as a service) has matured, there usually tends to be a few customers who have needs above the norm. And a common practice from software teams is to extend what is possible with their product through the use of webhooks.

This guide will help you gain a better understanding of what webhooks are, how they work, and what you can do to increase the functionality of your Beanstalk account.

What are they?

To put it simply, a webhook is a way for one server to “listen” to another. Here’s how Wikipedia defines it:

A webhook in web development is a method of augmenting or altering the behavior of a web page, or web application, with custom callbacks.

These callbacks are how this conversation occurs. When you set up a webhook, you tell the product you're using to send some information to a location of your choice. If we were to think about this using logical operators, it would look like this:

IF this happens, THEN send the details to HERE

So a service like Beanstalk can send information about your most recent push to your repository to your own web server. It does this using a well formatted JSON payload. This payload contains all the information you may want to know about the event. You can then act on this information on your server in a fashion that meets your needs.

JSON? Payload? Why would you want to mess around with this?

If these terms are new to you, it can all sound a little intimidating. But the end results can be worth the investment you have to make to get a webhook set up. First, there are services that allow you to include a webhook to connect to other web based services. And they do the programmatic work for you (see our example with Jenkins below).

After you’ve used a few of those, you can progress to creating your scripts to run on a server of your own.

Popular examples

What are some of the more popular uses for webhooks? Well, that’s a little like asking what are the more popular uses for pen and paper. Webhooks are flexible tools that can be used for a wide variety of purposes. However, we can review a few examples that illustrate how you can take advantage of this technology.

Help Scout is a customer support software service that also provides webhooks. With their available options, you could create a webhook to capture and process customer satisfaction ratings. These reactions could be posted to your server, then used to feed an internal analytics dashboard. And of course, you can connect your Help Scout account to various other services using webhooks.

Another service from Wildbit, Postmark allows you to send transactional emails for your product or application without having to manage an email infrastructure. For people have to send email, but do not want to deal with the headache of managing servers and email deliverability, Postmark is a godsend. However, even with a great service to handle your messages, bounces will happen. When it does, Postmark provides a bounce webhook that developers can use to perform some type of action when a bounce occurs.

These are just two examples of how you can put webhooks to work.

Webhooks & Beanstalk

Beanstalk has supported webhooks for quite some time. There are a few different options available, which we’ll cover here.

Classic vs. Modular Webhook integrations

In any repository in your Beanstalk account, you can find various integrations available under Repository > Settings. And you will see there are two options for webhooks, with the Classic Webhooks integration and the Modular Webhooks integration.

Note: The Classic Webhooks integration is deprecated and all new customers should use the Modular Webhooks integration. It has more functionality and flexibility than the Classic integration. We simply leave that available for customers who have webhooks of this type already in place.

Here are some of the advantages of the The Modular Webhooks integration:

• it allows you to create multiple hooks per repository, where as the Classic Webhooks integration only allowed 1 per repository
• it allows you to customize the triggers specified for the webhook
• it allows for retries when an attempted communication fails
• and you can see the entire history of your webhook, including request & response information

Again, unless you’ve used the Classic Webhooks integration in the past, there is no reason to use this option now.

Triggers available with the Modular Webhooks integration

There are far more possibilities with this integration than was previously possible wth the original. Here are the various events that can trigger a webhook delivery:

• commits (SVN)
• pushes (Git)
• comments
• branches (created or deleted)
• tags (created or deleted)
• code reviews (created, cancelled, reopened, approved)
• issues (created, resolved)

You can review the full list of our triggers, as well as some payload examples on our support site.

Types of webhooks available

In addition to our webhooks integrations, there are a couple of other spots where Beanstalk employs webhooks to allow you to do more with your repository. These options can be found in the settings for a release server in a deployment environment. We offer two types: pre- and post-deployment.

Depending on the complexity of your website or application, you might need to script certain tasks to happen before or after files are deployed. Some examples of these tasks might be renaming of certain configuration files, recompiling code, restarting of your Apache or Nginx, and busting cache - but the possibilities are 100% dependent on your application and web server configuration.

Beanstalk makes this possible with the webhooks options found in your release server.

While the Modular Webhooks integration gives the most flexibility, this pre– and post-deployment option is a quick and easy way to combine deployment related activities with your deployments themselves. This option also comes with a bonus: if you need the same setup between environments or repositories, you can copy a server and all its settings.

These two focused webhooks make extending your Beanstalk account that much easier.

Note: one item of importance is that the Modular Webhooks integration can replace the post-deployment option in your server settings, but cannot be used for running pre-deployment commands. That is where the option above is super helpful.

Zapier

Last, Beanstalk works with Zapier, a great service for connecting apps and automating your workflows. With full support for webhooks, Zapier can connect your Beanstalk account to many other services you may use (Help Scout, Dropbox, Twitter, Slack … the list is lengthy). We use Zapier ourselves to connect the different services we use.

What is required to make use of webhooks?

An important question you may be asking is, “How do I use this stuff?” Well, the list of requirements is small. You need:

• a publicly accessible web server
• some type of functionality to act on the data sent to your server

Due to the variety of server configurations, how to set your server up is beyond the scope of this guide. However, the basic premise is that your server must be configured to watch for POST events at the location you specified when setting up the webhook in Beanstalk.

Once that is in place, there is no shortage of things you can do with the data. To illustrate, let’s walk through a real use case.

Example: triggering a test build on a successful deployment

One common usage of webhooks is to generate a test in a CI (Continuous Integration) service. Here at Wildbit, our QA team likes to use Jenkins to test our releases. You can see the full details on how to integrate the CI service into Beanstalk.

The first step would be to create the desired URL within your Jenkins account. You can do this via the dashboard. Once you have created and tested the URL, it could be added to the post–deployment options within a release server in a given environment for your Beanstalk repository.

Use services like RequestBin for testing

Another helpful exercise is to test your webhooks before setting things up. This can be done very easily with services such as RequestBin.

Rather than testing things on your end server, you can generate a URL in RequestBin to add to your Beanstalk account.

Then you can perform the activity that would trigger the usage of this webhook to test. The payload will be delivered to RequestBin and displayed when you refresh the same page as shown above.

This will give you an idea what you’ll be working with.

Common Issues

As you are introducing an extra point of failure to your workflow, there are various types of problems one can have when using webhooks (with Beanstalk or any other web based service). Here are some of the most common.

Beanstalk cannot connect to your server

A common issue occurs when Beanstalk is unable to connect to your server. As mentioned in the requirements above, the URL you specify when setting up the webhook in Beanstalk must be publicly available. Ensure your URL location is available and appropriate ports are open.

Something goes wrong with the processing on your server

Once Beanstalk attempts to deliver the JSON payload to your server, things are all in your control. In order to get the best results, it makes sense to add some type of logging or error checks into whatever you want to do with the webhook.

Timeouts

The overall most common problem is that the commands you run on your server take too long to perform. Beanstalk has a maximum wait time of 240 seconds to wait for a response from your server. If the commands your run as a part of the process of using the webhook take longer than that, an incident can be generated in your Beanstalk account.

In this event, the actual task on your server may complete. But from Beanstalk perspective, it will be marked as a failure and an incident generated.

Conclusion

Overall, webhooks are a very handy addition to any web based service. With a little investment of your time, you can get more from the services you use to run your business. Beanstalk included.