What are webhooks?

Webhooks allow Rainforest to tell your app whenever tests are about to start or have completed. Webhooks are sent from Rainforest to an address configured in your site settings.

Webhooks can be useful to communicate to your app when to perform specific tasks, which we call "housekeeping". For example:

  • Resetting your database
  • Adding users for testers to your database
  • Restarting your webserver
  • Adding more servers

Rainforest supports two types of webhook, Simple and Advanced. Most people should use Simple webhooks. Advanced webhooks should only be used when any processes you need to run will definitely not return a response within 25 seconds.

Note: Using your existing Continuous Integration tool to manage your housekeeping tasks is recommended if possible.

If you’ve integrated Rainforest with your CI tool, most housekeeping tasks can be included in your existing CI configuration. If this is an option for you and your team, we strongly encourage managing your tasks in this way, rather than using webhooks.

To get set up, you can find CLI docs here:


If you do choose to use webhooks instead, we recommend that you include the webhook endpoint at the end of a run, rather than the beginning. This will prevent any delay to run times that might result from longer housekeeping tasks.

Simple Webhooks

Simple Webhooks can be used if your housekeeping takes less than 25 seconds to complete, and should be used in most cases.

Adding a webhook to your application:

To get started, you'll need to have an Engineer or Developer add a webhook endpoint into your app which Rainforest can call. The URL for this normally looks something like:


When the URL is requested, your application should:

  • Perform any housekeeping tasks required
  • Return a success (i.e. a 200 response code) if your housekeeping was completed.

Rainforest Setup:

Once you've added the webhook endpoint, simply enter the webhook address in your site settings page in Rainforest by clicking the environment that you want to add it to.

What happens when a Rainforest run starts?

When a Rainforest run starts the following things happen:

  • Rainforest makes a request to your webhook's URL
  • If the request is successful (i.e. a 200 response code), Rainforest will then start sending testers to your app
  • If no success is received, we will continue to retry the request

We send some information along with the request as parameters. It contains basic details about the run and for more advanced users, can be used to monitor progress using our API. Please contact us if you would like support on this.

Example request:


What happens when a Rainforest Run Ends?

We'll make the same request to your webhook's URL with the callback type of "after_run" in place of "before_run". This will let you know the run has completed and you can poll the API for results.

Advanced webhooks

Advanced webhooks should be used only for processes that are certain to take longer than 25 seconds to return a response at the beginning of a run.

Please note: Advanced webhooks will allow for longer setup processes, but may result in significant delays to run time. Please be aware of this possibility when using advanced webhooks.

To use advanced webhooks:

  • When Rainforest makes a request to your webhook's URL, respond immediately with a status 202 (Accepted) response code.
  • This alerts Rainforest that the webhook was successful, but setup was not able to complete within the request.
  • After responding, proceed with any necessary preparations to your testing environment.
  • Once your environment is ready, send a POST request to our callback endpoint (https://app.rainforestqa.com/api/1/callbacks) to signal Rainforest that you are ready to start the run

This endpoint requires 3 parameters:


The run ID we send you when we send you the first message.



(this is the only supported callback type at the moment)

A HMAC digest that you can generate with our auth gem (https://github.com/rainforestapp/auth)



You can find additional documentation for the callback endpoints here.

If you need help creating the callback URL in a different language, please contact us through our support channel.

  • Customers that use gem as stated on our documentation (here) please check you have the latest version.
  • Customers who have custom configurations, please contact us so we can help identify the best solution.
Did this answer your question?