Step 1 — Register a webhook endpoint
Open Webhooks (/integrations/webhooks). Register a new webhook by entering your HTTPS endpoint URL and selecting the events to subscribe to. Each webhook gets its own signing secret. Failed deliveries retry automatically with exponential backoff for 24 hours, so a brief outage on your side doesn't lose events — Mindbill keeps trying until your endpoint acknowledges receipt.
Step 2 — Subscribe to the right events
Mindbill emits 10 event types that mirror the bill lifecycle: bill.created, bill.sent, 999.received (syntax ack), 277ca.received (payer claim ack, accepted/rejected), 277.received (mid-cycle status), 835.received (remittance posted), bill.paid (100% of MLFS allowed remitted), bill.denied (F2, payment refused), plus second_review.dispatched and audit-complaint events. Subscribe only to what your integration acts on — e.g. a PM system might listen for 277ca.received and 835.received to track acceptance and payment.
Step 3 — Verify the HMAC-SHA256 signature
Every payload is signed with HMAC-SHA256 using the webhook's signing secret, so your endpoint can prove a request genuinely came from Mindbill before acting on it. The page includes a Node handler sample showing the verify-then-switch pattern: validate the signature, switch on the event type, read the typed payload (e.g. data.bill_id, data.amount_posted, data.adjustments[] on an 835), and return 200. Verifying the signature is non-optional — it's what keeps a forged request from posting a fake payment into your system.
Step 4 — Authenticate with API tokens
The REST v1 API lives at https://api.mindbill.example/v1, authenticated with a Bearer token. Create tokens at API Tokens (/integrations/api-tokens), each with a name and a scope (Read-only, Read + Write, or Admin) — e.g. a read-only token for an analytics ETL, a read+write token for a data pipeline. Tokens are bound to your tax ID and isolated from other tenants, are shown once then SHA-256 hashed at rest, and can be revoked anytime. Pair the API (push bills, pull reports) with webhooks (react to changes) for a full no-polling integration.
