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.

Response from your server

When responding to the webhook request, your server must respond with an 200 status code 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.

Retries

If a webhook request fails or times out (after 30 seconds), the request will be retried at least once, with a minimum delay of 5 seconds.

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. A simple example in Node.js would look as follows:

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(JSON.stringify(req.body));
  const digest = check.digest("hex");

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

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.

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: