Webhooks

Overview

Webhooks are user-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different applications or third-party APIs.

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

To handle a webhook, you'll need to build a small web application that can accept the HTTP requests. If you already have a web application set up, handling a webhook is usually as easy as adding a new URL to your application.

Expected response

An HTTP request will be made to a URI that you provide to Root. Your application performs whatever logic you feel necessary - read/write from a database, integrate with another API, or perform some computation - then responds to Root.

When responding, your server must respond with an HTTP 200 OK to indicate a successful receipt. Any other status code will be treated as a failure on the Root platform, and the webhook will be subsequently retried (see below).

Retries

If a webhook request fails or times out (after 30 seconds), the webhook will be retried up to 5 times, with 5 second intervals between tries.

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:

PropertyDefinition
webhook_idstring. The unique ID of the webhook.
eventobject. The event data - see webhook events for available event types.
verification_token
optional
string. An optional verification token token as provided during creating a webhook.
environmentstring. The dataset used by the webhook. Either sandbox or production.

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.

EventDescription
alteration_package_createdIndicates that an alteration package has been created on the policy.
policy_issuedIndicates that a new policy has been issued.
policy_cancelledIndicates that a policy has been cancelled.
policy_cancel_failedIndicates that a policy has failed to be cancelled.
policy_activatedIndicates that a policy has received its first payment and is now active.
policy_lapsedIndicates that a policy has lapsed.
policy_not_taken_upIndicates that a policy has been marked as not taken up.
policy_expiredIndicates that a policy has expired.
policy_lapse_failedIndicates that a policy has failed to be lapsed.
policy_updatedIndicates that a policy has been updated.
policy_reactivatedIndicates that a policy has been reactivated.
policy_requotedIndicates that a policy has been requoted.
policy_beneficiaries_updatedIndicates that a policy's beneficiaries have been updated.
policy_covered_people_updatedIndicates that a policy's covered people have been updated.
policyholder_createdIndicates that a policyholder has been created.
policyholder_updatedIndicates that a policyholder has been updated.
quote_package_createdIndicates that a new quote has been created.
application_createdIndicates that a new application has been created.
application_updatedIndicates that an application has been updated.
claim_openedIndicates that a new claim has been opened.
claim_sent_to_reviewIndicates that a claim has been sent to review.
claim_approvedIndicates that a claim has been approved.
claim_repudiatedIndicates that a claim has been repudiated.
claim_paid_outIndicates that a claim has been paid out.
claim_linked_to_policyIndicates that a claim has been linked to a policy.
claim_approval_acknowledgedIndicates that the decision to approve a claim has been accepted by the supervisor.
claim_goodwill_acknowledgedIndicates that the decision to approve a claim as goodwill has been accepted by the supervisor.
claim_no_claim_acknowledgedIndicates that the decision to reject a claim has been accepted by the supervisor.
claim_repudiation_acknowledgedIndicates that the decision to repudiate a claim has been accepted by the supervisor.
text_note_createdIndicates that a note has been added to a claim.
attachment_archivedIndicates that an attachment on a claim has been archived.
claim_checklist_item_checkedIndicates that a claim checklist item has been changed.
attachment_createdIndicates that an attachment has been added to a claim.
claim_checklist_item_note_createdIndicates that a note has been added to a claim checklist item.
claim_approval_not_acknowledgedIndicates that the decision to approve a claim has been rejected by the supervisor.
claim_goodwill_not_acknowledgedIndicates that the decision to approve a claim as goodwill has been rejected by the supervisor.
claim_no_claim_not_acknowledgedIndicates that the decision to reject a claim has been rejected by the supervisor.
claim_repudiation_not_acknowledgedIndicates that the decision to repudiate a claim has been rejected by the supervisor.
claim_goodwillIndicates that a claim has been approved as goodwill.
claim_no_claimIndicates that a claim has been rejected.
claim_reopenedIndicates that a claim has been reopened.
claim_updatedIndicates that a claim has been updated.
claimant_updatedIndicates that a claimant on a claim has been updated.
complaint_openedIndicates that a new complaint has been opened.
payment_method_assignedIndicates that a payment method has been saved on a policy.
payment_createdIndicates that a payment has been created
payment_failedIndicates that a payment has failed.
payment_succeededIndicates that a payment has succeeded.
payment_reversedIndicates that a payment has been reversed.
payment_updates_succeededIndicates that an attempt to update payments async succeeded
payment_updates_failedIndicates that an attempt to update payments async failed

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:

PropertyDefinition
webhook_idstring. The unique ID of the webhook.
verification_token
optional
string. An optional verification token token as provided during creating a webhook.
environmentstring. The dataset used by the webhook. Either sandbox or production.
notificationobject. The notification object.

Available subscriptions

The following webhook subscriptions are available for notifications:

Subscription nameDescription
notification_createdIndicates that a notification entity has been created created and stored on the Root platform. This does not, in and of itself, indicate that the notification has been sent or will be sent by the Root platform.
notification_sentIndicates that a notification (email, SMS or other) has been successfully sent by the Root platform.