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
eventobject 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 anotificationobject instead of anevent.
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:
- Requests are
POSTs. 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:
{
"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
- 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": "..."} - Save the
secretfrom the response asROOT_WEBHOOK_SECRET. - Create a sandbox policyholder through the API or the management dashboard to trigger a delivery.
- 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:
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
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.
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 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_idor 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 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, 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 responds to Root immediately, verifies the signature and retries delivery to your services.
Get started with Hookdeck for free and handle Root webhooks reliably in minutes.