Common webhook terminology
Webhooks have their own vocabulary. When reading documentation, debugging integrations, or discussing systems with your team, understanding these terms helps you communicate precisely and avoid confusion. This glossary covers the essential concepts you will encounter when working with webhooks.
Core concepts
Webhook refers to both the mechanism and the individual HTTP request. As a mechanism, webhooks are a pattern where one system notifies another via HTTP POST when something happens. As a request, "a webhook" means one specific notification sent from provider to consumer.
Provider (or sender, producer) is the system that sends webhooks. When Stripe sends you a notification about a payment, Stripe is the provider. Providers detect events, construct payloads, and handle delivery.
Consumer (or receiver, subscriber) is the system that receives webhooks. Your application that processes payment notifications is the consumer. Consumers expose endpoints, verify authenticity, and act on the data.
Endpoint (or webhook URL, callback URL, destination) is the URL where a consumer receives webhooks. This is typically an HTTPS URL pointing to a route in your application that handles incoming webhook requests. Providers send POST requests to this URL.
Events and payloads
Event is something that happened in the provider's system that triggers a webhook. A customer making a purchase, a repository receiving a push, or a message being sent are all events. Events are the reason webhooks exist.
Event type (or event name, topic) categorizes what kind of event occurred. Common formats include resource.action patterns like payment.completed, user.created, or order.refunded. Consumers use event types to route webhooks to appropriate handlers.
Payload is the data contained in the webhook request body. Payloads typically include information about the event, the affected resources, and metadata like timestamps. Most payloads use JSON format.
Fat payload contains complete resource data. When a user updates their profile, a fat payload includes all user fields. Consumers have everything they need without additional API calls.
Thin payload contains only identifiers and minimal metadata. That same user update might only include the user ID and event type. Consumers must call the provider's API to get full details.
Delivery and reliability
Delivery attempt is one try at sending a webhook to an endpoint. The first attempt happens when the event occurs. If it fails, subsequent attempts are retries.
Retry is a repeated delivery attempt after a failure. Providers retry when endpoints return error status codes, time out, or are unreachable. Retry strategies vary but typically use exponential backoff.
Exponential backoff is a retry strategy where the delay between attempts increases exponentially. First retry after 1 minute, then 5 minutes, then 30 minutes, and so on. This prevents overwhelming struggling endpoints.
Timeout is how long a provider waits for a response before considering delivery failed. Most providers use timeouts between 5 and 30 seconds. Slow endpoints trigger retries and may be disabled.
Dead letter queue (DLQ) is where webhooks go after exhausting all retry attempts. Instead of discarding failed webhooks, providers store them for later inspection or manual reprocessing.
At-least-once delivery means the provider guarantees every event will be delivered at least one time, but possibly more. Retries can cause duplicates. Most webhook systems use this guarantee.
Idempotency is the property where processing the same webhook multiple times produces the same result as processing it once. Idempotent handlers safely ignore duplicate deliveries.
Event ID (or delivery ID, idempotency key) is a unique identifier for each event. The same ID appears on all delivery attempts of the same event, allowing consumers to detect and deduplicate retries.
Security
Signature is a cryptographic proof that a webhook came from the claimed provider. Providers compute signatures using a shared secret and include them in request headers. Consumers verify signatures before processing.
HMAC (Hash-based Message Authentication Code) is the most common signature algorithm for webhooks. HMAC-SHA256 takes a secret key and the payload, producing a hash that only someone with the secret could generate.
Webhook secret (or signing secret, endpoint secret) is the cryptographic key shared between provider and consumer for signature verification. Keep this value confidential.
Timestamp is when the provider created the webhook. Included in signed data, timestamps prevent replay attacks where an attacker resends an old valid webhook.
Replay attack is when an attacker intercepts a valid webhook and sends it again later. Timestamps and short validity windows defend against this.
Subscription management
Subscription (or registration) is the configuration that tells a provider where to send webhooks and which event types to include. Creating a subscription typically involves providing an endpoint URL and selecting event types.
Webhook filtering is selecting which event types a subscription receives. Rather than getting all events, consumers can subscribe only to payment.completed and payment.failed, for example.
Verification challenge (or handshake) is a process where providers confirm an endpoint is valid and owned by the subscriber. Common methods include sending a challenge token that must be echoed back or requiring a specific response to a test request.
Advanced patterns
Fan-out is sending the same event to multiple endpoints. A single payment might trigger webhooks to your order system, analytics platform, and notification service.
Webhook gateway is a centralized service that receives webhooks and routes them to internal systems. Gateways handle signature verification, logging, and transformation in one place.
Backpressure is when a consumer cannot keep up with incoming webhook volume. Providers may slow down delivery, queue events, or disable endpoints that consistently fail.
Circuit breaker is a pattern where providers stop sending to consistently failing endpoints. After too many failures, the circuit "opens" and delivery stops until the endpoint recovers.