Webhooks

Receive real-time notifications when events occur in your account.

Overview

Webhooks allow your application to receive real-time notifications when events occur in your account. Instead of polling the API for updates, you can register an endpoint that we will call whenever relevant events happen.

Setting Up Webhooks

Go to Settings → Developer → Webhooks
Click Add Webhook and enter your endpoint URL
Select the events you want to receive
Save your webhook and copy the signing secret

Event Types

Event	Description
`filing.created`	A new filing was created
`filing.submitted`	A filing was submitted to the state portal
`filing.accepted`	A filing was accepted by the state
`filing.rejected`	A filing was rejected by the state

Payload Format

Webhook payloads are sent as JSON with the following structure:

{
  "id": "evt_abc123",
  "type": "filing.submitted",
  "created_at": "2026-01-15T10:30:00Z",
  "data": {
    "filing_id": "fil_xyz789",
    "policy_number": "POL-2026-001",
    "state": "TX",
    "status": "submitted"
  }
}

Signature Verification

All webhook requests include a signature in the X-Webhook-Signature header. You should verify this signature to ensure the request is authentic.

The signature is computed using HMAC-SHA256 with your webhook secret:

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """Verify webhook signature using HMAC-SHA256."""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
@app.post("/webhooks/regulus")
def handle_webhook(request):
    signature = request.headers.get("X-Webhook-Signature")
    if not verify_webhook(request.body, signature, WEBHOOK_SECRET):
        return Response(status=401)

    event = request.json()
    # Process the event...
    return Response(status=200)

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

// In your Express handler:
app.post('/webhooks/regulus', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  if (!verifyWebhook(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  // Process the event...
  res.status(200).send('OK');
});

Best Practices

Always verify signatures - Never process webhooks without verifying the signature
Return 200 quickly - Acknowledge receipt within 5 seconds, then process asynchronously
Handle duplicates - Use the event ID to deduplicate in case of retries
Use HTTPS - Webhook endpoints must use HTTPS for security

Retry Policy

If your endpoint returns a non-2xx status code or times out, we will retry the delivery:

1st retry: 1 minute after initial attempt
2nd retry: 5 minutes after 1st retry
3rd retry: 30 minutes after 2nd retry

After 3 failed attempts, the delivery is marked as failed. You can view delivery history in the webhook settings page.