Architecture

Nexus Broker is a serverless webhook relay that sits between external services and your infrastructure. It encrypts, queues, and delivers webhook payloads with zero knowledge of the contents. This page describes how the system is built and how data flows through it.

Core Components

1. Ingestion Layer

The public endpoint /wh/{slug} accepts unauthenticated HTTP POST requests. Each webhook has a unique, unpredictable slug that acts as an implicit credential. The ingestion layer validates the request body size, checks content-type headers, and hands the raw payload to the encryption engine. It responds immediately with a message ID and sequence number, before encryption completes asynchronously.

2. Encryption Engine

Every payload is encrypted server-side using the public key you registered with the webhook. The engine supports two schemes:

• RSA-2048 Hybrid — Generates a random AES-256 key, encrypts the payload with AES-256-GCM, then wraps the AES key with RSA-OAEP. The ciphertext, IV, authentication tag, and encrypted AES key are stored.
• X25519 ECIES — Generates an ephemeral X25519 keypair, performs ECDH with your public key, derives a symmetric key via HKDF-SHA256, and encrypts with AES-256-GCM. Provides forward secrecy since each message uses a unique ephemeral key.

The encryption key material (private keys, AES keys) is never persisted beyond the request lifecycle. Only the ciphertext and wrapped key are written to the database.

3. FIFO Queue

Encrypted messages are stored in a Firestore-backed FIFO queue. Each message is assigned a monotonically increasing sequence number scoped to its webhook. Messages move through explicit states: queued, locked, committed, error, or dead. Explicit locking prevents concurrent consumers from processing the same message. A scheduled job automatically releases expired locks and moves stale messages back to the queue.

4. Delivery API

Authenticated consumers interact with the queue through three operations:

• Dequeue — Fetches and locks the next available message in FIFO order
• Commit — Acknowledges successful processing, removes the message from the active queue
• Error — Reports a processing failure, releases the message for retry

5. Dead Letter Queue

Messages that exceed the maximum retry count are moved to the dead letter queue (DLQ). DLQ messages can be inspected, retried, or permanently discarded. The DLQ is per-webhook and accessible via the management API.

Architecture Diagram

Technology Stack

Data Flow

The complete path from ingestion to consumption follows these steps:

1. An external service sends an HTTP POST to /wh/{slug}
2. The ingestion layer validates the slug, checks the payload size against plan limits, and records the request headers
3. The encryption engine encrypts the raw payload with the webhook's registered public key
4. The encrypted payload is written to Firestore as a new queued message with a sequence number
5. The ingestion layer responds to the caller with the message ID and sequence number
6. A consumer calls the dequeue endpoint with an API key
7. The queue fetches the earliest unprocessed message, sets its status to "locked", and returns the encrypted payload
8. The consumer decrypts the payload locally using its private key
9. The consumer calls commit (success) or error (failure)
10. On commit, the message is marked as processed. On error, it is released for retry or moved to the dead letter queue if retries are exhausted

Infrastructure

Nexus Broker runs entirely on serverless infrastructure. There are no persistent servers to manage, patch, or scale. Vercel handles automatic scaling of API routes based on incoming traffic. Firestore provides automatic replication, strong consistency within a region, and built-in backup capabilities.

• Auto-scaling — Vercel spins up function instances on demand. From zero to thousands of concurrent requests without configuration.
• Global edge — Static assets and middleware run at the edge. API routes run in the nearest available region.
• Zero ops — No Kubernetes clusters, no container orchestration, no capacity planning. Deployments are Git-based via Vercel integration.
• Persistence — Firestore stores all encrypted messages, webhook configurations, and user data. Data is replicated across zones for durability.

Rate Limiting

Rate limits are applied per webhook and per user to ensure fair resource usage. Limits vary by plan:

When a rate limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating when to retry.