What Are Webhooks?

Real-time HTTP callbacks that notify your systems when events happen.

Instead of polling the API to check if a file has been processed, webhooks push notifications to your server the moment something happens. This is faster, more efficient, and eliminates the need for polling loops.

Common use cases:

Update your internal systems when a payroll file finishes processing
Alert your team when validation errors are found (RED rows)
Sync premium calculations back to your billing system

Register Your Endpoint

Add your webhook URL in the portal settings.

Navigate to Settings → Webhooks in your portal. Click "Add Webhook" and enter:

URL — your HTTPS endpoint (e.g., https://yourapp.com/webhooks/audit1)
Events — select which events to subscribe to
Secret — a shared secret for signature verification (auto-generated or custom)

HTTPS required. Webhook URLs must use HTTPS. HTTP endpoints are rejected for security.

Webhook Event Types

Choose which events trigger notifications.

Available webhook events:

file.validated — Phase 1 complete (class codes and states checked)
file.processed — Phase 2 complete (wages calculated)
file.premium_calculated — Phase 3 complete (premium amounts ready)
file.failed — processing failed (bad format, expired policy, etc.)
row.quarantined — individual rows flagged RED during validation

Start with file.premium_calculated. This is the most common event — it fires when the full pipeline completes and premium amounts are ready.

Payload Format

Understand the JSON payload your endpoint will receive.

Each webhook delivery is a POST request with a JSON body:

{
  "event": "file.premium_calculated",
  "timestamp": "2026-04-06T14:30:00Z",
  "data": {
    "file_id": "663a1b2c3d4e5f6789012345",
    "policy_number": "WC-2026-001",
    "employer": "Acme Corp",
    "total_rows": 45,
    "green_rows": 43,
    "red_rows": 2,
    "total_premium_cents": 1234567
  }
}

Headers include X-Audit1-Signature for verification and X-Audit1-Event with the event type.

Verify Webhook Signatures

Ensure webhook payloads haven't been tampered with.

Every webhook includes an X-Audit1-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.

// Node.js verification example
const crypto = require('crypto');

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

Always verify. Reject any webhook delivery where the signature doesn't match. This prevents spoofed payloads.

Test Your Integration

Send test events to verify your endpoint works correctly.

From Settings → Webhooks, click the "Send Test" button next to your registered endpoint. This sends a sample payload for each subscribed event type.

Your endpoint should:

Return a 200 OK response within 10 seconds
Verify the signature header
Process the event asynchronously (don't block the response)

All set! Your webhook will now receive real-time notifications. Failed deliveries are retried up to 3 times with exponential backoff. Check the webhook docs for the complete event reference.

Continue learning

Previous REST API Quick Start Submit payroll data programmatically via the API. Next tutorial SFTP Integration Guide Automate file delivery with secure SFTP.