Overview

Root uses webhooks to let your application know when events happen, such as when a policy is issued, or a claim is opened. When the event occurs, Root queues an HTTP POST request to the URL you configured for the webhook. You can set this URL through the API. The request payload will include details of the event.

A webhook endpoint is a destination on your server that receives requests from Root. Add a new endpoint to your server and make sure it's publicly accessible so we can send unauthenticated POST requests.

For a step by step guide on how to set up a webhook on Root and verify incoming requests, go to our Webhook setup and verification tutorial.

Response from your server

When responding to the webhook request, your server must respond with a status code in 2XX range (200 - 299) to indicate a successful receipt. Any other status code will be treated as a failure on the Root platform, and the request will be retried (see below).

The request from Root will time out after 30 seconds. If your server fails to respond within the timeout window, the request will be retried.

📘

Handle webhook events asynchronously

We strongly recommend that you configure your handler to process incoming events using an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries might overwhelm your endpoint hosts.

Asynchronous queues allow you to process concurrent events at a rate your system can support. It also reduces your server's response time to the webhook request.

Verifying requests

Every webhook includes an X-Hook-Signature header, containing an HMAC digest value. This digest is generated using a combination of the unique webhook secret (as provided when creating a webhook) and the webhook payload, using sha1 as the hashing algorithm.

To verify that the payload has originated from the Root platform, you can generate an HMAC digest on your server, and compare it to the one provided in the headers. Below are some simple examples:

const secret = "B3a8y1WotX7glI7OxZhX5EAd_6UJ7YEvTJBNQzano4dHjntn9_5AlyPg-dzpX76A";

app.post('/', (req, res, next) => {
  const signature = req.get("X-Hook-Signature");
  const check = crypto.createHmac("sha1", secret);
  check.update(req.body); // The raw (unparsed) request body string
  const digest = check.digest("hex");

  if (signature === digest) {
    res.status(200).send();
  } else {
    res.status(401).send()
  }
});

import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.SignatureException;
import java.util.Formatter;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;


public class HmacSha1Signature {
	private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";

	private static String toHexString(byte[] bytes) {
		Formatter formatter = new Formatter();
		
		for (byte b : bytes) {
			formatter.format("%02x", b);
		}

		return formatter.toString();
	}

	public static String calculateRFC2104HMAC(String data, String key)
		throws SignatureException, NoSuchAlgorithmException, InvalidKeyException
	{
		SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), HMAC_SHA1_ALGORITHM);
		Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
		mac.init(signingKey);
		return toHexString(mac.doFinal(data.getBytes()));
	}

	public static void main(String[] args) throws Exception {
		String hmac = calculateRFC2104HMAC("data", "key");

		System.out.println(hmac);
		assert hmac.equals("104152c5bfdca07bc633eebd46199f0255c9f49d");
	}
}

As an additional verification step, you can optionally provide your own verification token when creating a webhook. This token will be included in all webhook payloads as verification_token.

Retries

If a webhook request fails or times out (after 30 seconds), the request will be retried at least once, with a an approximate delay between 5s and 40s.

Priority

Each webhook has a priority of 1 or 2. Attempts for priority 1 webhooks are prioritised over priority 2 webhooks.

Production webhooks are priority 1 by default. If an attempt fails, or the server takes more than 5 seconds to respond, the webhook is assigned priority 2. Once an attempt succeeds with a response time less than 5 seconds, the webhook is upgraded back to priority 1.

All sandbox webhooks are priority 2 and their priority is never updated.

Automatic disable behaviour

Root automatically disables failing webhooks that meet the following criteria over a period of 48 hours, 96 hours, or 2 weeks:

• At least 10 queue events were triggered
• A 100% failure rate
• At least 12 hours elapsed between the earliest and latest queue event

Queue events for disabled webhooks are stored as failed and you can retry them.

Event webhooks

The majority of webhook subscriptions available on the Root platform are related to events.

Payload structure

Each event webhook has the following payload structure:

Certain webhooks contain additional top-level properties. For example, the policyholder_created webhook contains the policyholder object, and the policy_issued webhook contains the policy object.

Available subscriptions

The following events are available for subscription. An example of each event is documented on the events page.

If you want to subscribe to a webhook for an event not listed here, please submit an idea on our product roadmap portal describing your use case. We regularly review new ideas and will consider adding new subscriptions to the platform.

Notification webhooks

These webhooks relate to customer notifications - email and SMS notifications that go out to policyholders and claimants.

Payload structure

Notification webhooks have the following payload structure:

Available subscriptions

The following webhook subscriptions are available for notifications: