WebsiteWe're hiringCourses & Certifications→ Get started for free
Guides

Webhook setup and verification

Learn how to set up a webhook and verify webhook requests

Suggest Edits

Overview

In this tutorial, you will learn how to set up a webhook, trigger test events, and verify the security of incoming webhook requests. We'll use webhook.site as our webhook endpoint to verify that both the HMAC signatures and verification tokens are working as expected.

Read more about how webhooks work on Root in our API reference.

Step 1: Create your webhook

First, create a webhook that will notify you whenever a new policyholder is created on Root. Create a sandbox webhook over the API with this JSON body:

{
  "name": "Policyholder created",
  "description": "Test whenever a new policyholder is created",
  "url": "https://webhook.site/50f1b35f-f7d2-433b-9bed-9e86a9a39c82",
  "subscriptions": [
    "policyholder_created"
  ],
  "verification_token": "1234"
}

📘

Important configuration notes

  • Replace the URL with your unique url from webhook.site.
  • The verification token "1234" will be used later to verify webhook authenticity.
  • After creating the webhook, you'll receive a secret in the response body. Store this securely as it's needed for signature verification.

Step 2: Test the webhook

Let's verify the webhook is working by creating a test event on Root:

  1. Create a new sandbox policyholder, either via the API, or via the Root management dashboard.
  2. Open webhook.site at your unique URL and look for the incoming webhook request.
  3. You should see the request details including:
    • Headers (including the X-Hook-Signature header)
    • Raw payload (JSON string)
    • Your verification token

Step 3: Verify the webhook request

Now we'll verify that the webhook request is authentic by checking both the HMAC signature and verification token. Here's a script to help you verify incoming webhook messages:

#!/bin/bash

# Configuration
secret="your_webhook_secret"         # Replace with your webhook secret
payload='{"verification_token":"1234", ...}'  # Replace with the raw payload from Webhook.site
received_signature="your_x_hook_signature"    # Replace with X-Hook-Signature from Webhook.site

# Generate HMAC signature
computed_signature=$(echo -n "$payload" | openssl dgst -sha1 -hmac "$secret" | sed 's/^.* //')

# Verify signature
if [ "$computed_signature" == "$received_signature" ]; then
  echo "Signature is valid."
else
  echo "Signature is invalid."
fi

# Verify token
verification_token_in_payload=$(echo "$payload" | jq -r '.verification_token')
if [ "$verification_token_in_payload" == "1234" ]; then
  echo "Verification token matches."
else
  echo "Verification token does not match."
fi

# Configuration
$secret = "your_webhook_secret"         # Replace with your webhook secret
$payload = '{"verification_token":"1234", ...}'  # Replace with the raw payload from Webhook.site
$received_signature = "your_x_hook_signature"    # Replace with X-Hook-Signature from Webhook.site

# Function to compute HMAC-SHA1
function Get-HMACSHA1 {
    param(
        [string]$message,
        [string]$secret
    )
    
    $hmacsha = New-Object System.Security.Cryptography.HMACSHA1
    $hmacsha.Key = [System.Text.Encoding]::UTF8.GetBytes($secret)
    $messageBytes = [System.Text.Encoding]::UTF8.GetBytes($message)
    $signatureBytes = $hmacsha.ComputeHash($messageBytes)
    $signature = [System.BitConverter]::ToString($signatureBytes).Replace("-", "").ToLower()
    return $signature
}

# Generate HMAC signature
$computed_signature = Get-HMACSHA1 -message $payload -secret $secret

# Verify signature
if ($computed_signature -eq $received_signature) {
    Write-Host "Signature is valid."
} else {
    Write-Host "Signature is invalid."
}

# Verify token
# Parse JSON payload - requires PowerShell 3.0 or later
$payload_json = $payload | ConvertFrom-Json
$verification_token_in_payload = $payload_json.verification_token

if ($verification_token_in_payload -eq "1234") {
    Write-Host "Verification token matches."
} else {
    Write-Host "Verification token does not match."
}

To use this script:

  1. Replace the placeholder values with your actual webhook payload and secret.
  2. Run the script to verify both the signature and token.
  3. Check that both verifications pass.

🔍

Verification details

The script performs two key checks:

  • HMAC signature verification ensures both that the payload hasn't been tampered with, and that the secret specific to your webhook was used to generate the request.
  • The verification token adds an extra layer of security and can be specified by you, the user.

Updated about 1 month ago