Building Adal: predictable webhook delivery without black boxes

Webhook delivery systems have a reliability problem that nobody talks about openly. When a payment processor fires a webhook and your endpoint returns a 200, but the payload was malformed, the retry schedule is opaque, and your logs only capture part of the story, you're left reverse-engineering what happened from fragments. This is a distributed systems problem masquerading as an integration convenience.

The core issue is state management across trust boundaries. Your webhook provider owns the initial request. You own the response. But the delivery semantics, retry policies, and observability layer sit somewhere in between, often implemented as vendor-specific black boxes. When something fails, you can't easily distinguish between network issues, payload corruption, endpoint misconfiguration, or provider-side problems. The debugging surface area expands exponentially because you're reasoning about a system you don't fully control.

The Adal approach

Adal is a webhook delivery and observability platform built on a few explicit engineering principles. The design philosophy treats webhook infrastructure as a first-class distributed system rather than an afterthought bolted onto API integrations.

Permanent endpoint URLs address the stability problem. In typical webhook setups, providers rotate or regenerate endpoints, creating state synchronization issues. Adal maintains stable URLs that act as consistent entry points, regardless of what changes downstream. This is a simple architectural decision with significant implications for client-side configuration and retry logic.

Full request visibility means capturing everything: headers, payload, timing, response codes, and retry attempts. This is not just logging. It's structured observability that lets you reason about delivery behavior over time. The difference between "the webhook failed" and "the endpoint returned a 502 after 3.2 seconds with the following payload hash" is the difference between guessing and debugging.

Reproducibility over retry schedules

One of Adal's more interesting design choices is explicit replay without waiting for provider-side retry cycles. Most webhook systems implement exponential backoff at the provider level, which means you lose control over timing and can't easily re-trigger deliveries on demand.

Adal separates the replay concern from the delivery concern. You can re-fire a specific delivery attempt, with the same payload, to test endpoint behavior or recover from downstream failures. This is particularly valuable when you're testing webhook handlers in staging environments or debugging intermittent endpoint issues. The delivery logs become a replay audit trail rather than a fire-and-forget log.

This design trades simplicity for control. Provider-side retries are automatic and require no coordination. Adal's approach requires explicit replay triggers, but gives you deterministic control over timing and payload. For systems where delivery guarantees matter, this is a reasonable trade-off.

Regional delivery architecture

The stack includes a regional architecture for receiving and delivering webhook requests. This is not just about latency reduction. Regional delivery points create natural partitioning boundaries that improve fault isolation. If one region experiences issues, deliveries can be routed through alternative paths.

The Go backend with PostgreSQL and Redis provides the foundation for this. Go handles the concurrent delivery pipelines efficiently. PostgreSQL provides durable delivery state. Redis handles the real-time observability and retry queue management. This is a pragmatic stack choice that prioritizes operational simplicity over theoretical elegance.

Observability as a product feature

Most webhook platforms treat observability as a debugging aid, not a product feature. Adal inverts this. The delivery logs are structured to explain what happened, not just record that something occurred. Each delivery attempt includes request/response details, timing information, and failure context.

This approach reduces the mean time to understanding when deliveries fail. Instead of correlating logs across multiple systems, you get a unified view of delivery behavior. The trade-off is storage overhead and query complexity, but for teams that depend on reliable webhook delivery, this is a worthwhile investment.

Open source CLI, closed platform

The CLI is open source and written in Go, which creates an interesting hybrid model. You can inspect the tooling, contribute improvements, and understand the delivery semantics without committing to the full platform. The closed platform component provides the managed infrastructure, regional delivery, and persistent observability.

This model works well for developer tools where trust and transparency matter. Teams can evaluate the CLI locally, understand the delivery contract, and then decide whether the managed platform adds sufficient value. It's a pragmatic approach to building adoption while maintaining a sustainable business model.

Trade-offs and considerations

Adal makes a deliberate choice to prioritize explicitness over convenience. This means more configuration surface area, more moving parts to understand, and more decisions to make about delivery semantics. For teams that just need basic webhook delivery with minimal oversight, this might be more complexity than necessary.

The value proposition strengthens as webhook usage becomes more critical to your infrastructure. When you're processing thousands of webhook deliveries per hour, when delivery failures have business consequences, and when debugging time is expensive, the observability and control overhead becomes a net positive.

The regional architecture also introduces latency considerations. Cross-region delivery adds network overhead, which might be problematic for time-sensitive webhook processing. The design assumes that reliability and observability are more important than minimal latency, which is a reasonable assumption for most webhook use cases but worth evaluating for your specific requirements.

This is an early-stage project, but the design principles address real pain points in webhook infrastructure. The approach of treating webhook delivery as a distributed system problem, rather than an integration convenience, aligns with how production systems actually behave.