Using Webhooks

Overview

Webhooks allow Rainforest to notify you when a test is about to start and when it completes. Rainforest can send a webhook to an address configured in your site settings. Use webhooks to communicate with your app for housekeeping tasks, including:

• Resetting your database
• Adding users as testers to your database
• Restarting your web server
• Adding more servers

Rainforest supports two webhook types: simple and advanced. For most people, simple webhooks are sufficient. Use advanced webhooks when a process doesn’t return a response within 25 seconds. We recommend using your existing Continuous Integration tool to manage your housekeeping tasks whenever possible.

Note: We use the account owner’s API token for webhook calls.

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 your team, we strongly encourage managing your tasks in this way rather than using webhooks. For more information, refer to the Rainforest CLI documentation.

When using webhooks, we recommend including the endpoint at the start of a run rather than at the end. The test runs will start after housekeeping tasks are completed so your tests start on a clean environment.

Simple Webhooks

Use a simple webhook when your housekeeping task takes less than 25 seconds to complete. For longer tasks, use advanced.

Adding a Webhook to Your Application

To get started, ask an engineer to add a webhook endpoint to your app that Rainforest can call. The URL looks similar to this:

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

When the URL is requested, your application should:

• Perform any housekeeping tasks required
• Return a success response code (200) when your housekeeping is finished

Rainforest Setup

After adding the endpoint, key in the webhook address in your Sites and Environments settings page in Rainforest by clicking the environment you want to add it to.

Running a Test Using a Simple Webhook

When a Rainforest run starts, the following things happen:

• Rainforest makes a request to your webhook’s URL with a callback type of before_run.
• If the request is successful (200 response code), Rainforest sends testers to your app.
• If unsuccessful, we continue to retry the request.

Note: Rainforest sends information with the request as parameters, including basic details about the run. Advanced users can monitor the progress using our API. For more information, contact Support.

MethodPOST
URL	https://my-staging-app.com/webhook/rainforestqa
	{
 	  	"callback_type":"before_run",
    	 "options":{
Body		"run_id":"12345"
		},
      "digest":"ADIGESTSTRING"
    }

Ending a Rainforest Run

We make the same request to your webhook’s URL with a callback type of after_run. Doing so lets you know the run has completed, and you can poll the API for results.

Advanced Webhooks

Use advanced webhooks for processes that typically take longer than 25 seconds to return a response at the beginning of a run.

Running a Test Using an Advanced Webhook

When a Rainforest run starts, the following things happen:

• Rainforest makes a request to your webhook's URL with a callback_type of initializing_run, which responds immediately with an Accepted response code (200). This webhook request is made at the very start, before the run is initialized and validated, so you cannot use the CLI to query the run at this point. It is also possible for the run to error after this request. The purpose of this request is to give notice as early as possible of a run starting, so that your environment can start initializing as soon as possible and reduce run times. If you need to query the run during your environment initialization, use the before_run request below.
• Rainforest makes a request to your webhook’s URL with a callback_type of before_run, which responds immediately with an Accepted response code (202). Though Rainforest is alerted that the webhook was successful, the setup didn’t actually complete.
• You proceed with any necessary preparations for your testing environment after either the initializing_runrequest or the before_run request, depending on if you need to query the run for your initialization.
• Once your environment is ready, you send a POST request to our callback endpoint to signal Rainforest that you are ready to begin the run.

Endpoint Parameters

• run_id
  The run ID we send you in the first message.
• callback_type
initializing_run, before_run
• digest
  An HMAC digest you can generate using our authorization gem.

Notes

• Because of the asynchronous nature of sending webhooks, the order in which initializing_run and before_run are sent is not guaranteed. Webhook implementations should take this into account accordingly.
• In addition, it is possible to receive an after_run webhook without receiving a before_run webhook, for example if there is an error while initializing the run.

👍

Performance Tip

Since Rainforest waits for your webhook to return a response, using advanced webhooks can increase the time it takes for your run to complete.

Troubleshooting

If your test has failed with the error message "your webhook timed out", you will receive an email with more information on the failure reason.
Example: If your Rainforest was unable to connect to the server for the provided you will receive the following email. In this scenario you would need to troubleshoot your server as well as verify you have allowed access to our Webhook IP Addresses.

Webhook IP Addresses

34.73.160.85
35.231.233.87
34.74.224.232

Support

For more information on callback endpoints, see our API Documentation. If you need help creating the callback URL in a different language, contact Support.

• For customers using our auth gem, make sure you have the latest version.
• For customers with custom configurations, contact Support so we can help identify the best solution.

If you have any questions, reach out to us at [email protected].