Webhook Guide

Receive Signed Events When Bill Audit Workflows Move Forward

Preflix AI webhooks support asynchronous partner workflows: audit milestones, report availability, letter drafts, and dispute status updates.

Read API Docs Request Sandbox

Examples are synthetic. Production event delivery requires partner setup, signing secrets, and privacy review.

Preflix AI webhook timeline with signed event cards, retry path, and endpoint target

6Event types

2Signature headers

100%Duplicate tolerance

Setup

Treat Webhooks Like Production Infrastructure

Signed events should be verified, queued, and processed idempotently so partner workflows stay reliable during retries or outages.

1
Create An Endpoint
Use a server-side HTTPS endpoint dedicated to Preflix AI events and avoid sharing it with unrelated product webhooks.
2
Choose Event Types
Subscribe only to the events your workflow needs, such as audit completion or dispute status changes.
3
Verify Signatures
Recompute the HMAC with the timestamp and raw payload before parsing or queueing any work.
4
Return Quickly
Acknowledge valid events with a fast 2xx response, then process longer work asynchronously.

Event Catalog

Subscribe To The Smallest Useful Set Of Events

Every event should map to a specific partner action, such as fetching a report, updating a case, or notifying an advocate.

Preflix AI webhook event catalog
Event	When It Fires	Partner Action
`bill.created`	A partner bill record is accepted.	Create or update the local case shell.
`bill.document_ready`	Required document references are attached.	Show that audit preparation can begin.
`audit.started`	Preflix AI begins review.	Move the partner case to active analysis.
`audit.completed`	A structured audit report is available.	Fetch the report and notify the user or advocate.
`letter.ready`	A requested letter draft is prepared.	Present the draft for review before sending.
`dispute.status_changed`	A dispute workflow is updated.	Sync status, deadline, and follow-up tasks.

Signed Payload

Verify Before Processing The Event

Preflix AI should send timestamped signatures in headers so receivers can reject tampered, stale, or replayed events.

preflixai-timestamp
Unix timestamp used in the signature base string.

preflixai-signature
HMAC digest computed with the endpoint signing secret.

Example Eventaudit.completed

{
  "id": "evt_7b2",
  "type": "audit.completed",
  "created_at": "2026-01-15T19:04:12Z",
  "data": {
    "bill_id": "bill_8f4",
    "report_id": "report_33",
    "status": "complete"
  }
}

Retry And Failure Logic

Delivery Should Be Durable, Observable, And Idempotent

Partners should expect at-least-once delivery and build receivers that tolerate duplicate events, temporary outages, and delayed retries.

Exponential Backoff

Retries should spread over increasing windows with jitter so partner outages do not create traffic spikes.

Idempotent Processing

Store event IDs before work starts so duplicate deliveries do not create duplicate reports, tasks, or notifications.

Dead-Letter Review

Repeated failures should land in an operations queue with endpoint, event type, response code, and retry count.

Testing Checklist

Prove The Receiver Before Turning On Production Events

A webhook receiver is only ready when security checks, retry handling, logging hygiene, and replay behavior have all been exercised.

Verify signatures with the raw request body before JSON parsing.
Reject events with stale timestamps or unknown event IDs.
Return 2xx only after validation and durable queueing succeed.
Keep payloads out of logs unless fields are explicitly safe.
Use separate webhook secrets for sandbox and production.
Replay sample events before enabling production subscriptions.

Integrate Events With The API

Use Webhooks To Keep Partner Cases In Sync

Open API Reference Request Sandbox