Webhook URL

Overview

Webhook URL is the complete HTTPS address registered with a provider as the destination for webhook deliveries. It is used to route event notifications to the correct application environment and handler. It differs from a webhook endpoint, which is the receiving server route and implementation rather than the configured address value.

A typical implementation works as follows: The merchant registers the URL, the provider stores it with event subscriptions and secrets, and deliveries target that address until configuration changes. A Webhook URL handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.

Common risks include typos and wrong environment. Important failure modes include typos, wrong environment, public query secrets, redirects, expired certificates, DNS changes, and orphaned URLs. These failures can interrupt or expose events. A receiver should treat transport acknowledgement and successful downstream processing as separate states for Webhook URL.

Core controls require teams to validate ownership, require HTTPS, keep secrets outside the URL, restrict redirects, test reachability, version paths, and monitor changes. Replay of Webhook URL should preserve original identifiers and timestamps so historical processing cannot masquerade as a new event.

Operational evidence should include URL, environment, subscription, secret version, verification status, owner, creation time, and last successful delivery. Webhook URL should be documented alongside Webhook Endpoint, Callback URL, and API Base URL.

For Webhook URL, the event identifier, signature result, delivery attempt, and resulting business state should remain connected throughout processing. The Webhook URL path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state.