What are webhooks?

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

Webhooks can be useful to communicate to your app when to perform specific tasks, which we call "house keeping". 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 house keeping tasks is recommended if possible

If you’ve integrated Rainforest with your CI tool, most house keeping 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:

https://github.com/rainforestapp/rainforest-cli

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 house keeping tasks.

Simple Webhooks

Simple Webhooks can be used if your house keeping 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:

https://my-staging-app.com/webhook/rainforestqa

When the URL is requested, your application should:

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

Rainforest Setup:

Once you've added the webhook endpoint, simply enter the webhook address in your site settings page in Rainforest.

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:

run_id 

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

'before_run'

callback_type 

(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)

digest

Support

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.  

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