Webhook patterns for crypto invoice automation

Polling dashboards does not scale past a few dozen invoices a week. Webhooks push invoice.paid and payment.confirmed to your stack in near real time — triggering ERP journal entries, Slack alerts, provisioning workflows, or data warehouse upserts. This guide covers patterns that work in production, not just in a tutorial curl.

Events you should subscribe to first

• invoice.sent — client notification pipeline, CRM activity log
• payment.detected — ops alerts for large amounts (optional)
• payment.confirmed — revenue recognition, fulfillment unlock
• invoice.paid — close invoice lifecycle, stop dunning

Start with payment.confirmed and invoice.paid. Add detected events only if operations needs early warning before finality.

Idempotency is non-negotiable

Webhooks retry on non-2xx responses. Your consumer will see duplicates. Store event IDs (or invoice ID + event type + confirmation height) in a deduplication table before side effects. Returning 200 after a no-op duplicate is correct behavior.

Sample ERP mapping

For payment.confirmed: debit crypto clearing account, credit accounts receivable for fiat invoice total, attach tx hash in memo field. For invoice.paid: mark invoice closed in ERP if not already. Exact accounts depend on your chart; the invariant is one journal entry per economic event, not per webhook retry.

Failure handling and observability

Settlematic's delivery log shows HTTP status and timestamp per attempt. Alert on sustained 5xx from your endpoint. Use a dead-letter queue for events that fail schema validation — usually a version skew after you deploy a new field.

Security practices

• HTTPS only on production endpoints
• Verify payload signatures when signing ships (roadmap) — until then, restrict by network allowlist
• Separate API keys for webhook management vs invoice CRUD
• Never log full payloads with PII into public log aggregators

Testnet-driven integration tests

Run webhook consumers against testnet payments before mainnet. Same event shapes, different chain IDs. Pair with the staging playbook in our testnet guide so finance and engineering sign off on the same run.

When webhooks are boring — same schema, idempotent handlers, monitored retries — your billing stack becomes infrastructure instead of a weekly fire drill.