Webhooks & Events

Open-source API gateway for microservices

fluxgate webhook create --type route.error --url https://hooks.yourdomain.com/fg --secret sk_live_9x8m2p --timeout 3s

Concept

Event-Driven Notification Concept

FluxGate emits structured HTTP POST requests whenever a routing rule triggers, a downstream service returns a 5xx status, or an operator pushes a configuration change. Instead of polling the gateway dashboard, your monitoring stack receives real-time signals directly from the edge.

Each webhook subscription binds to a specific event namespace. The gateway maintains an in-memory event bus that decouples traffic processing from outbound HTTP calls. When a match occurs, FluxGate serializes the event payload, signs it with your shared secret, and dispatches it to the registered endpoint. This architecture guarantees that webhook delivery never blocks request routing, preserving sub-10ms latency for your microservices.

Configuration

Webhook Configuration

Define subscription rules through the FluxGate CLI or the admin REST API. Each subscription requires a target URL, event filter, and authentication header.

Traffic Events

Capture request lifecycle milestones including route.matched, upstream.timeout, and rate.limit.exceeded. Configure thresholds to filter noise and only forward events exceeding your defined QPS caps.

Error Signals

Monitor downstream health with service.5xx, tls.handshake.fail, and circuit.broken. FluxGate aggregates consecutive failures into a single batched notification to prevent webhook storms during outages.

Config Changes

Track infrastructure drift with route.created, policy.updated, and secret.rotated. Use these events to sync your internal service registry or trigger automated compliance audits.

Create Subscription View CLI Reference

Payload Structure

Every webhook delivery follows a strict JSON envelope that includes metadata, the event type, and a versioned data object. FluxGate signs each request using HMAC-SHA256 with your configured secret.

The X-FluxGate-Signature header contains the timestamp and hash. Verify the signature on your endpoint to prevent replay attacks. The payload structure remains stable across minor gateway releases, with breaking changes only introduced in major version bumps.

{
  "id": "evt_9f8a7b6c5d4e3f2a1b0c",
  "type": "route.error",
  "timestamp": "2024-05-14T09:32:11Z",
  "gateway_node": "us-east-1-prod-04",
  "data": {
    "request_id": "req_7h3k9m2p",
    "path": "/api/v2/inventory",
    "status_code": 503,
    "upstream_service": "stock-manager",
    "latency_ms": 2450
  }
}

Retry Logic

Retry Logic & Delivery Guarantees

FluxGate implements exponential backoff with jitter to handle transient network failures and endpoint maintenance windows. Dropped webhooks do not impact gateway performance or request routing.

When a target endpoint returns a 4xx or 5xx status, or fails to respond within 3 seconds, FluxGate queues the event for retry. The default schedule attempts delivery at 15s, 2m, 10m, and 1h after the initial failure. Failed events are retained for 24 hours before being purged and logged to the audit trail. You can adjust the maximum retry count and timeout thresholds per subscription to match your operational SLAs.

Monitor delivery health through the webhook.delivery.failed event or query the /v1/webhooks/status endpoint. FluxGate provides a dedicated retry dashboard that surfaces skipped endpoints, signature verification failures, and payload size rejections.