Webhooks

The gateway is the termination point for inbound webhooks from our resources and the origin point for outbound webhooks to consumers. No consumer ever receives a vendor webhook directly. No vendor ever receives a consumer webhook directly. The boundary is ours.

Inbound: Our Resource → Gateway

The spike built POST /v1/webhooks/members to receive Salesforce events. In the gateway model, this becomes a resource-specific path: POST /v1/webhooks/salesforce/members.

Requirements (Not All in the Spike)

• Signature verification — every inbound webhook verifies a vendor-provided signature. For Salesforce, a custom header signed with a shared secret. Reject if missing, invalid, or replayed.
• Dedupe — vendors retry. Store received event IDs in Redis with a 24-hour TTL. Reject duplicates.
• Async processing — webhook handlers enqueue work, don't process synchronously. Return 202 Accepted immediately. A worker pulls from the queue and does the actual processing.

POST /v1/webhooks/salesforce/members
  → verify signature
  → check dedupe
  → enqueue event
  → return 202

Outbound: Gateway → Consumer

The gateway can also send webhooks to consumers for events the consumer has subscribed to. This is useful when a consumer wants to be notified of events from our resources without polling.

Event Subscription Model

Consumers register interest in events via the gateway. The gateway handles vendor-specific subscription mechanisms (Platform Events, webhooks, etc.) and normalizes the event format for consumers.

Delivery Guarantees

• At-least-once delivery
• Bounded retries with backoff
• Idempotency keys on every delivery
• Consumers must dedupe on event ID

Platform Events (Salesforce)

For Atlantes publishing events to our Salesforce org, the gateway uses Platform Events via the REST API. SF triggers a flow or apex trigger. The gateway handles authentication, retry, and signature.

Change Data Capture (Future)

If and when Atlantes needs to mirror our SF state for read-side queries, the gateway subscribes to CDC via the Streaming API. The gateway normalizes CDC events into the same webhook format as Platform Events.

Reliability Summary

Direction	Retries	Dedup	Auth
Resource → Gateway	Resource's responsibility	Gateway dedupes by event ID	Signature verification
Gateway → Consumer	Gateway's responsibility	Consumer dedupes by event ID	Signed by gateway
Gateway → Resource	Gateway's responsibility	Idempotency key	Resource auth (JWT, etc.)