Webhook Event Pipeline for Automation & Billing Platforms

1. Overview & Event Architecture #

The BEX Webhook Event Pipeline provides an asynchronous, real-time event-driven push architecture that bridges network activities with external management software, billing platforms (e.g., WHMCS, Blesta), custom ERPs, and automation platforms (e.g., Zapier, Make). By eliminating the need for inefficient HTTP polling, BEX streams state transitions, usage alerts, and account events instantaneously, enabling distributors and partners to trigger automated billing, customer notifications, and provisioning workflows with zero latency.

2. Webhook Event Types & Payload Protocols #

BEX dispatches structured, versioned JSON event payloads over secure HTTPS POST channels. Event types are categorized by functional domain:

• Account & Balance Events:
  • account.balance.low — Triggered when a reseller or user balance drops below set thresholds.
  • account.balance.depleted — Dispatched immediately upon balance exhaustion.
  • account.topup.success — Confirms successful cryptographic or manual top-ups.
• Session & Usage Events:
  • session.bandwidth.capped — Fired when an active connection hits a allocated quota.
  • session.anomaly.detected — Indicates suspicious traffic spikes or security flags.
• Reseller Lifecycle Events:
  • subreseller.created — Dispatched when a new downstream sub-account is provisioned.
  • subreseller.status.changed — Emitted upon suspension, reactivation, or privilege modification.

Payload structure format (raw text JSON):

{“event_id”: “evt_98f41a02”, “event_type”: “account.balance.low”, “timestamp”: 1758882000, “data”: {“reseller_id”: “res_88201”, “remaining_tokens”: 150, “threshold_tokens”: 200, “currency_equivalent_usd”: 15.00}}

3. HMAC-SHA256 Signature Verification & Security #

To prevent webhook spoofing, payload tampering, and replay attacks over public networks, BEX enforces strict cryptographic verification headers on all outgoing webhook payloads:

• Cryptographic Signatures: Every HTTP POST request includes an X-BEX-Signature header generated using HMAC-SHA256 with the partner’s unique webhook secret key.
• Anti-Replay Timestamping: Payloads include an X-BEX-Timestamp header. Receiving servers validate that the request timestamp is within a 300-second window to reject replayed requests.
• IP Whitelisting & TLS 1.3: Webhooks originate exclusively from dedicated, static BEX delivery IP clusters using mandatory TLS 1.3 encryption.

4. Exponential Backoff, Dead Letter Queues (DLQ) & Idempotency #

To guarantee reliable event delivery even during receiving server downtime or network degradation, BEX operates a resilient queue delivery pipeline:

• At-Least-Once Delivery & Retries: If an endpoint fails to return a 2xx HTTP status, BEX initiates an automated retry strategy using exponential backoff with jitter across 24 hours (e.g., retries at 10s, 1m, 5m, 1h, 6h, 24h).
• Dead Letter Queue (DLQ): Messages failing all retry attempts are safely quarantined into a Dead Letter Queue. Resellers can inspect failed events and execute manual replay triggers via the BEX portal or API.
• Consumer Idempotency: Receiving platforms use the unique event_id key to ensure idempotent processing, preventing duplicate actions if a webhook is delivered more than once.

5. Key Strategic Benefits #

• Real-Time Automated Billing: Instant synchronization with external platforms for suspended access, top-ups, and overage invoicing.
• Elimination of Polling Overhead: Saves network bandwidth and server resources by replacing high-frequency API polling with event pushes.
• Cryptographic Integrity: Zero-trust signature verification ensures received events are authentic and unmodified.