Quickstart A — Receive policy data via webhook

What you'll build: a small web server that receives extracted policy data from InsurGrid, verifies it's genuine, and prints it. By the end you'll have handled a real (test) policy-data webhook end to end.

Time: ~20 minutes.

Prerequisites (from Get started):

• An InsurGrid account with access to the API section.

• Your signing secret (from API credentials).

• Node 18+ or Python 3.9+ installed.

• ngrok (or any tunnel) if you're on your local machine.

---

Step 1 — Get your signing secret

From the dashboard's API section, copy your signing secret and put it in an environment variable so it never lands in your code:

export INSURGRID_SIGNING_SECRET="whsec_...your secret..."

You'll use it in Step 4 to prove each webhook really came from InsurGrid.

Step 2 — Stand up an endpoint · server

Create a tiny server with one route that accepts a POST. Read the raw request body as well as the parsed JSON — you need the raw bytes for signature verification in Step 4.

Node (Express):

// server.js — run with: node server.js
const express = require("express");
const app = express();

// Keep the raw body; we need the exact bytes to verify the signature.
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}));

app.post("/hooks/insurgrid", (req, res) => {
  res.sendStatus(200);          // Step 3: acknowledge fast
  console.log("Received:", req.body.topic);
  // signature check + processing come next
});

app.listen(3000, () => console.log("Listening on :3000"));

Python (Flask):

# server.py — run with: flask --app server run --port 3000
from flask import Flask, request

app = Flask(__name__)

@app.post("/hooks/insurgrid")
def insurgrid_hook():
    raw = request.get_data()          # exact bytes, for the signature check
    event = request.get_json()
    print("Received:", event["topic"])
    return "", 200                    # Step 3: acknowledge fast

Step 3 — Acknowledge fast, process later

Notice both handlers return 200 right away. Do any slow work (saving to your DB, calling other services) after you respond — see Set up a webhook endpoint for why this matters. For this quickstart, printing is enough.

Step 4 — Expose your endpoint & register it · local dev

If you're on your machine, start a tunnel so InsurGrid can reach you:

ngrok http 3000

Copy the https://… URL it prints, append /hooks/insurgrid, and add it in the dashboard's API section as the staging URL for the client-submission topic. (Full walkthrough: Expose your local endpoint.)

Step 5 — Verify the signature · server

Every webhook carries an x-signature header: an HMAC-SHA256 of the raw request body, computed with your signing secret. Recompute it on your side and compare — if it doesn't match, reject the request.

New term — HMAC signature: a fingerprint of the message made with a shared secret. Because only you and InsurGrid know the secret, a matching fingerprint proves the message is genuine and unaltered. Compute it over the exact raw bytes you received — if you re-serialize the parsed JSON first, the bytes differ and the check will falsely fail. This is the #1 first-timer bug.

Node:

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  // timing-safe compare avoids leaking info via response time
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature || ""));
}

app.post("/hooks/insurgrid", (req, res) => {
  const ok = verify(req.rawBody, req.get("x-signature"), process.env.INSURGRID_SIGNING_SECRET);
  if (!ok) return res.sendStatus(401);   // not from InsurGrid — reject
  res.sendStatus(200);
  handle(req.body);
});

Python:

import hmac, hashlib, os

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

@app.post("/hooks/insurgrid")
def insurgrid_hook():
    raw = request.get_data()
    if not verify(raw, request.headers.get("x-signature", ""),
                  os.environ["INSURGRID_SIGNING_SECRET"]):
        return "", 401                    # not from InsurGrid — reject
    handle(request.get_json())
    return "", 200

Prefer a different scheme (Bearer token, Basic auth, or an API-key header) instead of a signature? You can configure that per endpoint — see Register your endpoint & choose an auth type.

Step 6 — Read the payload · server

A verified policy-data webhook looks like this:

{
  "topic": "client-submission",
  "data": {
    "document_link": "https://files.insurgrid.com/…/declaration.pdf",
    "policy_type": "Personal Auto",
    "policy": { "provider": "…", "policy_number": "…" },
    "policyholder": { "first_name": "…", "last_name": "…" },
    "vehicles": [ … ],
    "…": "…extracted fields, depending on policy_type…"
  }
}

Key fields:

Field	Type	Meaning	Example
topic	string	The event type. For policy data it's client-submission.	"client-submission"
data.document_link	string (URL)	A time-limited link to the source declaration-page file.	"https://files.insurgrid.com/…"
data.policy_type	string	A descriptive label for the insurance line — a hint, not a fixed code (don't hard-match).	"Personal Auto", "Homeowners"
data.*	object/array	The extracted policy fields. The set depends on policy_type.	see Webhook events & payloads

⚠️ document_link expires. It's a temporary download link. If you need the file, fetch and store it on your side promptly — don't save the link and expect it to work later.

The full field list per policy type is in the Webhook events & payloads reference.

Step 7 — De-duplicate · server

Delivery is at-least-once: the same event may occasionally arrive more than once (for example, if a retry overlaps a slow success). So make your handler idempotent — processing the same event twice must be harmless.

The policy-data payload has no dedicated event-id field, so de-duplicate on a hash of the payload contents — identical content means it's the same event. Record hashes you've already handled and skip repeats:

// server (sketch)
const crypto = require("crypto");
function handle(event) {
  const key = crypto.createHash("sha256")
    .update(JSON.stringify(event.data)).digest("hex");   // content fingerprint
  if (alreadyProcessed(key)) return;      // skip duplicate
  markProcessed(key);
  // …save the policy data…
}

See Delivery & de-duplication for patterns. (The form-submission event is simpler — it carries a submission_id you can key on directly.)

Step 8 — Try it out (sandbox)

1. In the API section, use Send test event to fire a sample client-submission at your staging URL.

2. Watch your server log the topic and the payload.

3. Check the delivery log in the dashboard — you'll see the attempt and your 200 response.

If nothing arrives, jump to Troubleshooting → "My webhook isn't arriving".

Step 9 — Go live

When staging works end to end:

1. Deploy your endpoint to a real HTTPS URL.

2. Add that URL as your production client-submission webhook.

3. Switch to your production signing secret and API token.

4. Run the Integration checklist.

---

Next steps

• Embed a form to collect submissions →

• Webhook events & payloads (all fields) →

• Verify signatures — deeper dive →