Core concepts

Overview

Adal is webhook infrastructure for receiving, inspecting, temporarily storing, forwarding, retrying, and replaying HTTP webhook requests while preserving the request as received.

Adal sits between an external sender and your application as an observable delivery layer: it 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.

Important: Adal preserves the original HTTP method, URI, headers, and body. It does not enrich the Request with business data, rewrite its contents, or make application decisions on your behalf.

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 records 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 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 and configuration;

• 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 webhooks for inspection where request storage is enabled, 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 when it is retained.

A retained 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 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 original 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.

Important: A successful Delivery means only that Adal received the expected HTTP response from the Destination. It does not prove that the application completed its business operation, committed data, or finished an action in another system.

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 retained 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. Complete Request contents and delivery configuration must not be copied into ordinary application logs, traces, metrics, alerts, error reports, support messages, or analytics systems.

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 without recording sensitive webhook data unnecessarily;

• 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, monitoring, and recovery mechanisms.

When Adal is a good fit

Use Adal when you need predictable, inspectable webhook delivery:

• local development without a public IP, using Adal CLI;

• inspecting a provider's real payload before you implement a handler;

• bridging temporary Destination downtime with retention, retries, and Replay;

• controlled automatic and manual retries for failed Deliveries;

• replaying a retained Request without waiting for the sender;

• delivering one Request to several Destinations (fan-out);

• region-specific processing and limited retention;

• debugging silent delivery failures with Delivery history.

When Adal is not a good fit

Do not treat Adal as:

• permanent storage, a backup, or an archive;

• an exactly-once delivery system;

• a replacement for your application queues, databases, logs, monitoring, or recovery;

• a payment processor;

• an authentication provider;

• a security gateway;

• proof that a Destination completed its downstream business operation.

A successful Delivery means Adal received the expected HTTP response from the Destination. Retries and Replay can create duplicate deliveries; Destination handlers must verify signatures, validate input, stay idempotent, and deduplicate when a stable provider event ID is available.

Glossary

Related pages

• Adal compared to related tools — decide when Adal fits your use case.

• Quickstart — create your first delivery flow and send a test webhook.

• Servers — learn about ingest URLs, regions, methods, limits, and deletion.

• Requests — inspect contents, statuses, and Replay behavior.

• Destinations — configure Direct HTTP, Adal CLI, and delivery history.

• Retries — understand schedules, manual actions, duplicates, and idempotency.

• Data storage — learn about regional storage, retention, and deletion.

• Security — protect data, connections, and credentials.