Agent skill
Root Webhooks Skill
Receive and verify Root webhooks. Use when configuring Root webhook endpoints, debugging x-hook-signature-256 signatures, or handling policyholder_created, policy_issued, claim_opened.
Install this skill
npx skills add hookdeck/webhook-skills --skill root-platform-webhooks
Receive Root insurance policy, policyholder and claim events.
When to Use This Skill
- Configure a receiver for Root webhook deliveries.
- Diagnose
x-hook-signature-256verification failures. - Handle
policyholder_created,policy_issued,claim_opened.
Setup
Create a webhook through Root's API for the organisation and environment, with the required subscriptions. Save the secret returned by the create response. A separately chosen verification_token is echoed in the body and does not replace signature verification.
Set ROOT_ in the server environment. Read setup before enabling delivery.
Verification (core)
x-hook-signature-256 contains a bare hex digest over the raw body. Use HMAC-SHA256 with the secret's UTF-8 bytes. Verify the original bytes before parsing JSON. Validate the digest format, then compare equal-length buffers in constant time.
After extracting the documented digest and constructing message as described in verification, the comparison is:
const expected = crypto.createHmac('sha256', secret).update(message).digest();
if (digest.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(digest)) return false;
const received = Buffer.from(digest, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
No timestamp is included in the signed message. These examples do not invent an age check from unsigned fields.
Complete handlers and tests: Express, Next.js, FastAPI.
Event Handling
Event deliveries carry event.type. Notification deliveries carry notification instead and may have no event type. Verify X-Hook-Signature-256; the older X-Hook-Signature uses deprecated SHA-1.
Return 2xx within 30 seconds and keep handlers fast. Acknowledge notification payloads you do not process, and make event handling idempotent.
Local Development
npx hookdeck-cli listen 3000 root-platform --path /webhooks/root-platform
Use port 8000 for FastAPI. The CLI provides a local tunnel and inspection UI; no account is required to start.