Using Webhooks

Learn how to get notifications from Rainforest using simple and advanced webhooks.


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 end of a run rather than at the beginning. Doing so ensures longer housekeeping tasks do not result in delayed run results.

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:

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.


Adding a webhook address.

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.

Body        "run_id":"12345"

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, 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.
  • 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
    before_run is currently the only supported callback type for this endpoint.
  • digest
    An HMAC digest you can generate using our authorization gem.


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.


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].

Did this page help you?