# Guide to Root Webhooks: Features and Best Practices

Root is an embedded-insurance platform that runs policies, claims, complaints and premium payments through its API and management dashboard. Root's webhooks tell your systems when something happens to those records, such as a policy being issued or lapsing, a claim being approved or a premium payment failing.

This guide covers creating Root webhooks over the API, the difference between event and notification webhooks, `X-Hook-Signature-256` verification, and how Root's priority and auto-disable rules respond to slow or failing endpoints.

## What are Root webhooks?

Root webhooks are created through the API for one organisation and one environment, sandbox or production. Each has a URL and a list of subscriptions, and Root returns a signing secret when you create it. You can also set your own `verification_token`, which Root echoes in every payload.

There are two kinds:

* **Event webhooks** are the majority. They carry an `event` object for actions on policies, applications, claims, payments and other records.
* **Notification webhooks** (`notification_created`, `notification_sent`) report the emails and SMS messages Root sends to policyholders and claimants. They carry a `notification` object instead of an `event`.

## Root webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-hook-signature-256` |
| Body | JSON |
| Event routing | Body field `event.type` |

From Root's [webhooks reference](https://docs.rootplatform.com/reference/webhooks):

* Requests are `POST`s. Any status from 200 to 299 is success, and anything else is a failure.
* The request times out after 30 seconds. Failed or timed-out requests are retried at least once, after roughly 5 to 40 seconds.
* Production webhooks start at priority 1. A failure or a response slower than 5 seconds drops a webhook to priority 2, and a fast success restores it. Sandbox webhooks are always priority 2.
* Root disables a webhook automatically when, over 48 hours, 96 hours or 2 weeks, it has at least 10 queue events spanning at least 12 hours, all of which failed. Those events are stored as failed and can be retried.
* New subscriptions can be requested through Root's product roadmap portal.

## Events and payloads

Route event webhooks on `event.type`. Root lists about 54 subscriptions. The first few are:

| Event routing | Body field `event.type` |

The rest cover the policy lifecycle (`policy_expired`, `policy_lapse_failed`, `policy_updated`, `policy_reactivated`, `policy_requoted`, beneficiary and covered-people updates), `policyholder_created` and `policyholder_updated`, `quote_package_created`, applications, claims (`claim_opened`, `claim_sent_to_review`, `claim_approved`, `claim_repudiated`, `claim_paid_out`, `claim_fulfilled`, `claim_reopened`, the acknowledgement events and more), `text_note_created`, attachments, checklist items, `complaint_opened` and payments (`payment_created`, `payment_failed`, `payment_succeeded`, `payment_reversed`, `payment_method_assigned` and the async `payment_updates_*` pair).

An event delivery's top level holds `webhook_id`, `event`, `environment` (`sandbox` or `production`) and `verification_token` if you set one. Some types add more: `policyholder_created` includes the `policyholder` object and `policy_issued` the `policy`. Root's events reference shows only the `event` part. This is its `claim_approved` example:

```json
{
  "event": {
    "reason": "Valid approval reason",
    "type": "claim_approved",
    "claim_id": "14dbf7d3-de87-4296-8240-fdc633fea979",
    "created_at": "2017-05-25T14:15:53.696Z",
    "requested_by": {
      "type": "user",
      "id": "00000000-0000-0000-0000-000000000001"
    }
  }
}

```

`requested_by.type` is `user` or `system`. No complete delivery, with the envelope and extra objects, is published, and a couple of the events-page examples aren't valid JSON, so capture a sandbox delivery before writing parsers.

## Setting up Root webhooks

1. Create a webhook with Root's API, in sandbox first. Root's setup guide uses a body like `{"name": "Policyholder created", "description": "...", "url": "https://example.com/webhooks/root-platform", "subscriptions": ["policyholder_created"], "verification_token": "..."}`.
2. Save the `secret` from the response as `ROOT_WEBHOOK_SECRET`.
3. Create a sandbox policyholder through the API or the management dashboard to trigger a delivery.
4. Repeat in production, where the webhook gets its own secret.

To route through Hookdeck, use the Hookdeck source URL as the webhook `url` and give a Root source the secret. Use separate sources for sandbox and production so each has the right secret. For local development:

```bash
npx hookdeck-cli listen 3000 root-platform --path /webhooks/root-platform

```

## Securing Root webhooks

`X-Hook-Signature-256` is the hex HMAC-SHA256 of the raw request body, keyed with the webhook secret. Root still sends `X-Hook-Signature` with HMAC-SHA1 for compatibility but recommends SHA-256. The optional `verification_token` in the body is a second check you can add, not a replacement for the signature, since anyone who has seen a payload knows it.

### Node.js verification

```javascript
const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-hook-signature-256'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The handler verifies the signature, checks the `verification_token` you chose, and separates notification deliveries from event deliveries.

```javascript
const express = require('express');

const app = express();

app.post('/webhooks/root-platform', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.ROOT_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  let delivery;
  try {
    delivery = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!delivery || typeof delivery !== 'object' || Array.isArray(delivery)) return res.sendStatus(400);
  try {
    const token = process.env.ROOT_VERIFICATION_TOKEN;
    if (token && delivery.verification_token !== token) return res.sendStatus(401);

    if (delivery.notification) {
      await recordNotification(delivery.webhook_id, delivery.environment, delivery.notification);
    } else if (delivery.event?.type) {
      await queue.add('root-event', {
        type: delivery.event.type,
        environment: delivery.environment,
        event: delivery.event,
        policy: delivery.policy,
        policyholder: delivery.policyholder,
      });
    }
  } catch {
    return res.sendStatus(503);
  }

  res.sendStatus(200);
});

```

Hookdeck's Root source checks `X-Hook-Signature-256` and ignores the SHA-1 header and the token. It answers Root with `200` and records mismatches as failed verification. Root signs no timestamp, so Hookdeck applies no time window.

> **Make Root webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) answers Root in well under 5 seconds, so production webhooks stay at priority 1, and holds events for retry while your claims or billing service recovers.

## Root webhook limitations and pain points

### Slow responses lower your priority

**The Problem:** Deliveries to your endpoint get queued behind other customers' webhooks.

**Why It Happens:** A production webhook that fails or takes more than 5 seconds is moved to priority 2 until an attempt succeeds in under 5 seconds. Sandbox webhooks are always priority 2.

**Workarounds:**

* Respond as soon as the event is stored, well inside 5 seconds.
* Don't use sandbox timing to judge production latency.

**How Hookdeck Can Help:** Hookdeck acknowledges Root immediately, so your webhook stays at priority 1 however long your own processing takes.

### Few retries before an event fails

**The Problem:** A short outage can leave events failed on Root's side.

**Why It Happens:** Root retries a failed request "at least once" after roughly 5 to 40 seconds. Beyond that, the number of retries isn't stated.

**Workarounds:**

* Retry stored failed events from Root once you've recovered.
* Reconcile policies, claims and payments through the Root API after downtime.

**How Hookdeck Can Help:** Hookdeck accepts each event first time and retries your service on its own schedule, with bulk replay for anything that still failed.

### Auto-disable after sustained failure

**The Problem:** A webhook that keeps failing is switched off.

**Why It Happens:** Root disables webhooks with a 100% failure rate over 48 hours, 96 hours or 2 weeks, given at least 10 queue events spanning 12 hours.

**Workarounds:**

* Alert on your own error rate well before 48 hours have passed.
* Once fixed, retry the events Root stored as failed for that webhook.

**How Hookdeck Can Help:** Since Hookdeck returns `200` to Root, the webhook's failure rate stays at zero while your service is down.

### Notification webhooks have no type

**The Problem:** `notification_created` and `notification_sent` look the same on arrival.

**Why It Happens:** Notification payloads carry a `notification` object and no event type, so the body doesn't say which subscription fired.

**Workarounds:**

* Create one webhook per notification subscription and tell them apart by `webhook_id` or URL path.
* Keep notification and event webhooks on separate endpoints.

**How Hookdeck Can Help:** Separate Hookdeck sources, or connections filtered on `webhook_id`, keep the two notification streams apart.

## Best practices

### Route on environment

Every delivery says whether it's `sandbox` or `production`. Reject sandbox events in production systems, even if a URL gets mixed up.

### Use the extra top-level objects

`policy_issued` and `policyholder_created` include the full object, which saves an API call. For other types, fetch the record by the ID in `event`.

### Process in the background

Thirty seconds is the timeout, but five is the threshold that matters for priority. Queue events and acknowledge. Our [guide to asynchronous processing](/webhooks/guides/why-implement-asynchronous-processing-webhooks) covers the approach.

### Expect repeats

Retries and manual retries of failed events can deliver the same event twice. Make payouts, payment updates and emails [idempotent](/webhooks/guides/implement-webhook-idempotency), keyed on the record ID and `event.type`.

## Conclusion

Root's webhooks are created over the API per environment, report policy, claim, payment and notification activity, and are signed with a hex HMAC-SHA256 in `X-Hook-Signature-256`. Your endpoint's speed affects delivery: under 5 seconds keeps production webhooks at priority 1, and persistent failure gets them disabled.

[Hookdeck Event Gateway](https://hookdeck.com) responds to Root immediately, verifies the signature and retries delivery to your services.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Root webhooks reliably in minutes.