Webhooks

API Design

Meaning

Webhooks are user-defined HTTP callbacks that one application sends to another when a specific event occurs, replacing the need for constant polling. They address the inefficiency and latency of polling APIs by pushing data the moment something happens. Developers reach for webhooks when integrating services that need real-time event notifications without maintaining persistent connections.

Primary Function

Event-driven integration

Communicative Purpose

Enables real-time, push-based communication between services so consumers react to events immediately instead of repeatedly polling for changes.

Pattern

Função primária

Event-driven integration

Propósito comunicativo

Enables real-time, push-based communication between services so consumers react to events immediately instead of repeatedly polling for changes.

Situações de gatilho

SaaS integrations: notifying external systems when a payment succeeds or a user signs up; CI/CD: triggering downstream pipeline stages when a commit lands; ChatOps: posting build results to Slack or Teams channels.

Contextos

REST APIs, SaaS platforms (GitHub, Stripe, Shopify), CI/CD pipelines, payment processors, messaging platforms, microservices event buses.

Padrão

Colocados típicos

HMAC signature verification
retry with exponential backoff
idempotency keys
X-Event-Type header
dead-letter queue
HTTPS endpoint
shared secret.

Substituições comuns

Polling API (simpler but higher latency and load)
WebSocket (bidirectional
persistent connection)
message queue subscriber (Kafka
RabbitMQ — stronger delivery guarantees but heavier infrastructure)
Server-Sent Events (one-way push over a long-lived HTTP connection).

Erros comuns

Skipping signature verification — allows attackers to forge events and trigger unintended actions; No idempotency handling — duplicate deliveries cause double-processing of payments or notifications; Exposing the endpoint without authentication — any party who learns the URL can spam it; Assuming synchronous semantics — webhook delivery is asynchronous, so the receiver must not block the sender's response on processing; Returning non-2xx on transient errors — causes premature retry exhaustion instead of letting the sender back off.

Similar / contraste

WebSocket — bidirectional persistent connection vs one-way event push; Polling — client-driven vs server-pushed; Pub/Sub — decoupled via broker vs direct HTTP callback; Long polling — holds connection open vs fires immediately on event.

Interferências

Coming from message-queue ecosystems (RabbitMQ/Kafka): may assume guaranteed at-least-once delivery with broker-managed retries — webhooks have no built-in durability and require the sender to implement retry policy; Coming from frontend polling: may assume the client initiates every request — webhooks invert this so the server pushes.

Família do chunk

event-driven architecture
HTTP callbacks
pub/sub messaging
polling APIs
Server-Sent Events
message queues
idempotency keys.

Nuance

Do not use webhooks for high-volume, low-latency event streams where you need ordered, replayable delivery — a message broker is more appropriate. Each delivery costs an outbound HTTPS request, so very chatty events can hammer the receiver; batch or debounce upstream. Boundary condition: receivers must respond within the sender's timeout (often 5–10s) — long processing should be offloaded to a background job.

Efeito pragmático

Correctly implemented webhooks eliminate polling overhead, cut integration latency from minutes to seconds, and let small services react to third-party events without maintaining always-on connections.

Dica de memória

Webhooks: like leaving your phone number with a delivery service so they call you the moment your package arrives — instead of you calling them every five minutes to ask.

Upgrade path

Event streaming with durable brokers (Kafka, AWS SNS/SQS, NATS) when you need replay, ordering, or fan-out to many consumers.

Frequência: HighFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

from flask import Flask, request, abort import hmac, hashlib app = Flask(__name__) SECRET = b'shared-secret' @app.route('/webhooks/order', methods=['POST']) def order_webhook(): signature = request.headers.get('X-Signature', '') expected = hmac.new(SECRET, request.data, hashlib.sha256).hexdigest() if not hmac.compare_digest(signature, expected): abort(401) event = request.json fulfill_order(event['order_id'], event['items']) return '', 200

import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def send_webhook(url, payload, secret): session = requests.Session() retry = Retry(total=3, backoff_factor=1, status_forcelist=[500, 502, 503, 504]) session.mount('https://', HTTPAdapter(max_retries=retry)) body = requests.utils.json.dumps(payload).encode() signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() response = session.post(url, data=body, headers={ 'Content-Type': 'application/json', 'X-Signature': signature, 'X-Event-Type': payload['type'], }, timeout=10) response.raise_for_status()

import stripe stripe.api_key = 'sk_test_...' @app.route('/webhooks/stripe', methods=['POST']) def stripe_webhook(): payload = request.data sig_header = request.headers.get('Stripe-Signature') try: event = stripe.Webhook.construct_event(payload, sig_header, 'whsec_...') except (ValueError, stripe.error.SignatureVerificationError): abort(400) if event['type'] == 'checkout.session.completed': mark_order_paid(event['data']['object']['id']) return '', 200