Core concepts

Overview

Adal provides infrastructure for receiving, inspecting, storing, and delivering HTTP webhooks. It sits between an external sender and your application as an observable delivery layer: Adal accepts requests at a stable public URL, shows you exactly what arrived, and forwards accepted requests to the Destinations you configure.

The model has four core entities. A Server receives the webhook, an accepted webhook becomes a Request, a Destination defines where that Request should go, and a Delivery tracks one Request on its way to one Destination.

How the core entities fit together

1. An external service sends a webhook to the Adal Server URL.
2. The Server checks whether the request can be accepted and stores it as an Adal Request.
3. Adal creates a separate Delivery for every configured Destination.
4. Adal or Adal CLI makes a delivery attempt and records the outcome.
5. After a temporary failure, Adal may make more attempts according to that Destination's retry settings.

A Server receives many Requests. A single Request can fan out to several Destinations, giving it multiple independent Deliveries. Each Delivery has its own attempt history and final outcome.

Server

A Server is the public entry point for your webhooks. It has a stable, region-specific URL that you configure in an external service such as GitHub, Stripe, or Telegram.

A Server determines:

• the region where requests are received and processed;
• which HTTP methods are allowed;
• the retention period available under your plan;
• the Destinations that receive accepted Requests.

The Server URL accepts requests at its root and at nested paths, including query strings. A Server with no Destinations can still receive and store webhooks for inspection, but it does not forward them automatically.

Request

A Request is Adal's record of one HTTP request received by a Server. Every accepted webhook becomes a separate Request with its own identifier, received time, status, and scheduled deletion date.

An accepted Request contains the data needed for inspection and delivery:

• the HTTP method, full URI, path, and query parameters;
• the headers and body;
• the received time, size, and technical metadata;
• related Deliveries and their attempt history.

Acceptance is not delivery. A Request in Adal confirms that Adal accepted the webhook. It does not mean that any Destination has received or processed it.

If an incoming request does not meet the Server or account requirements, Adal may reject it before storing the full contents. A rejected request retains only minimal troubleshooting metadata, and no Deliveries are created.

Destination

A Destination is a configured target for Requests received by a Server. It belongs to one Server and holds the connection and retry settings for that delivery route.

Direct HTTP

Adal sends the Request directly from its infrastructure to a public HTTP or HTTPS URL. This option works well for an internet-accessible application and does not require Adal CLI to be running.

Adal CLI

Adal passes the Request over a secure outbound connection to a connected CLI client, which then forwards it to a local or private service. Your application does not need a public IP address or a temporary tunnel.

Multiple Destinations create a fan-out flow in which one Request is delivered to several systems. A failure on one route does not undo a successful Delivery on another.

Deliveries and delivery attempts

A Delivery tracks one Request being sent to one Destination. A delivery attempt is one actual network call within that Delivery. The initial send and every automatic or manual retry appear in the same attempt history.

For Direct HTTP, Adal makes the request. For a local route, the connected Adal CLI client makes it. The saved HTTP method, URI, headers, and body are forwarded to the Destination.

An attempt succeeds when Adal receives an HTTP response in the 2xx range. Responses in the 4xx or 5xx range, network errors, and timeouts are treated as failures.

Retry and Replay

Both actions send data again, but they operate at different levels:

Automatic retries follow the settings of each Destination. A manual retry repeats one specific Delivery. Replay runs the retained Request through the Server's current delivery flow again, which is useful after changing your application or Destination configuration.

A retry may follow a lost response or timeout even though the application already performed the action. Retries and Replay can therefore create duplicates and repeated side effects. Exactly-once delivery is not guaranteed.

Regions and retention

You choose a region when you create a Server. The region appears in the public URL and determines where Adal receives and processes its Requests. Request and Delivery data remain associated with that region.

Accepted Requests are retained for a limited period based on your plan and configuration. Every Request has its own scheduled deletion date. Once retention expires, its contents and delivery history are deleted, so you can no longer inspect the Request, retry its Delivery, or Replay it.

Deleting a Server stops new intake and removes its Destinations. Requests accepted earlier may remain until their scheduled deletion dates. Adal does not reuse the subdomain of a deleted Server.

Adal is not permanent storage, a backup system, or an archive. Keep your own copies of any data you need to retain long term.

Security and shared responsibility

Treat the entire incoming Request and the complete Destination configuration as potentially sensitive. Secrets can appear in URLs, paths, query parameters, headers, bodies, tokens, API keys, and signing secrets.

Adal encrypts sensitive data at rest and uses secure connections in transit. It keeps complete Request contents and delivery configuration out of ordinary application logs, traces, metrics, alerts, and support messages.

Adal makes webhook receipt and delivery observable and controllable, but it does not replace validation and resilience in your application. A Destination handler should:

• verify the sender's signature or other authentication evidence;
• validate the structure and permitted values of incoming data;
• be idempotent and handle repeated delivery safely;
• deduplicate events using a stable provider event ID when one is available;
• maintain its own logs, monitoring, and error handling;
• account for partial fan-out failures and repeated side effects.

Adal is not a payment processor, authentication provider, security gateway, or replacement for your application's queues, databases, backups, and recovery mechanisms.

Glossary

Related pages

• Quickstart — create your first delivery flow and send a test webhook.
• Servers — ingest URLs, regions, methods, limits, and deletion.
• Requests — contents, statuses, inspection, and Replay.
• Destinations — Direct HTTP, Adal CLI, and delivery history.
• Retries — schedules, manual actions, and idempotency.
• Data storage — regional storage, retention, and deletion.
• Security — protecting data, connections, and credentials.