Webhook Subscription
Pronunciation: WEB-hook sub-SKRIP-shun
Also known as: Event Webhook Subscription, Callback Subscription
Definition
Webhook Subscription is a stored registration that tells a provider which endpoint, event types, account scope, and delivery settings should receive webhook notifications. It is configuration for future delivery, not an individual webhook event and not proof that the endpoint successfully processed any event. A production implementation should authenticate subscription changes, validate endpoint ownership, restrict event scope, store signing configuration, support rotation and disablement, expose status, and test delivery before production use.
Overview
How it works and where it fits
The principal risks include events sent to an obsolete or attacker-controlled endpoint, overbroad event access, secret exposure, duplicate subscriptions, disabled endpoints remaining active, and environment mix-ups. A receiver should treat transport acknowledgement and successful downstream processing as separate states for Webhook Subscription.
A production implementation should authenticate subscription changes, validate endpoint ownership, restrict event scope, store signing configuration, support rotation and disablement, expose status, and test delivery before production use. Replay of Webhook Subscription should preserve original identifiers and timestamps so historical processing cannot masquerade as a new event.
Useful measures include active subscriptions, delivery success by subscription, disabled or failing endpoints, secret age, duplicate registrations, and time to remove obsolete destinations. Webhook Subscription is closely connected to Webhook Consumer, Webhook Acknowledgement, and Payload Signature. The Webhook Subscription path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state.
Recovery for Webhook Subscription should combine replay controls with an authoritative status check rather than trusting delivery history alone. A Webhook Subscription handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.
Business actions triggered by Webhook Subscription should be idempotent and should verify the current object state before fulfillment or accounting updates. Monitoring for Webhook Subscription should track delivery age, signature failures, duplicate rate, retry exhaustion, and unresolved business events.
Related glossary concepts
Webhook Endpoint; Webhook URL; Webhook Log
Primary reference
Example
A merchant subscribes to payout-status notifications for one account. The service stores the subscriber identity, selected event types, destination URL and credential version. When a payout changes state, delivery is attempted only under that active subscription and its authorized scope.
Comparison
Subscription describes event-delivery configuration, not a paid recurring commercial plan. Make unsubscribe and rotation actions explicit, verify the destination, and prevent unauthorized tenants from registering another tenant's payout events. A subscription can be active even while an endpoint is down; queue and retry policies determine eventual delivery.
Key Takeaway
An active event subscription does not guarantee that its destination processed each delivery.
Sources
- CloudEvents Specification — Cloud Native Computing Foundation (2026-08-03)
- Webhook — OxaPay (2026-08-03)
- HTTP Message Signatures — IETF (2026-08-03)