{
  "id": "webhook",
  "title": "Webhook",
  "lang": "en",
  "source_lang": "en",
  "summary": "A webhook is an event-triggered HTTP request that sends information from one application to another, enabling automated notifications and integrations.",
  "category": "computer-science",
  "subcategory": "software",
  "type": "concept",
  "aliases": [
    "Web hook",
    "HTTP callback"
  ],
  "generated_at": "2026-11-05",
  "model": "pro/gpt-6.1-sol",
  "url": "https://aiwiki.page/en/webhook/",
  "translations": {
    "zh-Hans": {
      "url": "https://aiwiki.page/zh/webhook/",
      "json": "https://aiwiki.page/zh/webhook.json"
    }
  },
  "sections": [
    {
      "heading": "",
      "text": "A webhook is a mechanism by which one application sends an HTTP request to another application when a specified event occurs. The receiving application provides an endpoint, usually identified by a URL, to which the sending application delivers information about the event. Webhooks commonly notify external systems about events such as a completed payment, a new software commit, or an updated customer record. They are an integration pattern built on web technologies, not a single standardized protocol."
    },
    {
      "heading": "Operating model",
      "text": "A webhook reverses the direction of a typical information request. In an ordinary application programming interface (API) interaction, a client asks a service for information. With a webhook, the service initiates a request to a previously configured recipient when relevant information becomes available.\n\nA typical interaction has five stages:\n\n- Registration: A recipient supplies an endpoint URL and selects the events it wants to receive. Configuration may occur through a website, an API, or a subscription protocol.\n- Event creation: An action in the source application produces an event, such as an order changing status.\n- Delivery: The source sends an HTTP request to the registered endpoint, commonly using the POST method.\n- Acknowledgment: The recipient returns an HTTP response indicating whether it accepted the request.\n- Processing: The recipient interprets the event and performs work, either before responding or asynchronously afterward.\n\nThe request body commonly uses JSON, although some implementations use XML, form-encoded data, or other representations. Request headers may carry event types, delivery identifiers, timestamps, and authentication information.\n\nThe sending service is the HTTP client during delivery, even if it otherwise acts as a server for its own users. This distinction follows the client–server model: roles depend on the particular exchange, not on a permanent classification of the applications."
    },
    {
      "heading": "Events and payloads",
      "text": "A webhook payload describes an event or signals that additional information is available. Two common designs are:\n\n- Data-bearing notifications: The payload contains a representation of the affected resource, such as an order and its updated status.\n- Reference notifications: The payload contains an identifier or resource URL, and the recipient retrieves further details through an API.\n\nData-bearing notifications can reduce additional requests and preserve information about a particular transition. Reference notifications can keep messages smaller and allow the recipient to retrieve the resource’s current state under its own access permissions.\n\nAn event is not necessarily equivalent to the current state of a resource. For example, an “order created” notification may arrive after the order has already been canceled. A payload may describe the state at event creation, whereas a subsequent API request may return a newer state.\n\nEvent identifiers, delivery-attempt identifiers, resource identifiers, timestamps, and schema versions serve different purposes. In particular, several delivery attempts may correspond to the same logical event. Their exact meanings depend on the provider’s event model."
    },
    {
      "heading": "Comparison with related mechanisms",
      "text": "Polling\n\nWith polling, a client repeatedly asks whether anything has changed. This is simple to implement when an API already exists, but frequent requests consume resources even when no events occur. Infrequent requests increase notification delay.\n\nWebhooks reduce repeated checking by sending notifications when events become available. However, they require the recipient to expose a reachable endpoint or use an intermediary. Polling remains useful for reconciliation, recovering missed changes, and integrating with services that do not offer webhook delivery.\n\nStreaming and messaging\n\nWebhooks usually deliver discrete HTTP requests. They differ from a persistent connection, such as a WebSocket, through which applications can exchange messages without initiating a new HTTP request for every message.\n\nWebhooks also differ from a message broker’s subscription interface. A broker may provide durable retention, consumer offsets, replay, and ordering guarantees. A webhook service may offer some of these features, but none follows automatically from using HTTP.\n\nIn event-driven architecture, webhooks often connect independently operated services. They can also feed internal queues or stream-processing systems, separating external notification delivery from downstream processing."
    },
    {
      "heading": "Reliability and delivery semantics",
      "text": "An HTTP exchange does not, by itself, guarantee that an event’s intended business effect occurs exactly once. Webhooks inherit the uncertainty of distributed computing: a recipient may process a request successfully, but the sender may not receive its acknowledgment.\n\nRetries and duplicate deliveries\n\nProviders commonly retry deliveries after connection failures, timeouts, or selected error responses. Retry policies differ in duration, frequency, and treatment of HTTP status codes. Some use increasing delays, often with random variation to avoid synchronized retry bursts.\n\nRetries can produce duplicate deliveries. Recipients therefore often use idempotent processing: receiving the same event repeatedly has the same intended effect as receiving it once. This may involve recording processed event identifiers or using an application-specific uniqueness constraint.\n\nDeduplication alone is insufficient if recording an event and applying its effect can fail independently. Where both operations affect the same database, a database transaction can coordinate them. Effects involving external services may require additional coordination or downstream idempotency support.\n\n“At least once” delivery generally permits duplicates; “at most once” permits missed events. Neither property should be assumed without an explicit provider contract. Claims of “exactly once” require a defined scope and cannot be inferred merely from a successful HTTP response.\n\nAcknowledgment and durable acceptance\n\nMany implementations interpret a 2xx response as successful delivery. This usually acknowledges acceptance, not completion of every downstream action.\n\nA common design validates a request, records it durably, and returns a response before performing lengthy work. A queue can then feed background workers. Returning success before any durable acceptance creates a loss window if the recipient fails immediately afterward.\n\nOrdering and recovery\n\nEvents may arrive out of order because of concurrent delivery, retries, or network delays. Resource versions and sequence numbers can help identify stale updates when the provider supplies them. Timestamps alone do not always establish a reliable total order.\n\nRecovery mechanisms may include delivery logs, manual redelivery, retained event histories, and periodic comparison with the source API. Webhooks are therefore often treated as timely notifications rather than the sole authoritative record of system state."
    },
    {
      "heading": "Security",
      "text": "A public webhook endpoint receives requests from outside its own trust boundary. Authentication, payload validation, and resource controls are separate concerns.\n\nTransport and sender verification\n\nHTTPS protects traffic in transit through Transport Layer Security. In its usual configuration, it authenticates the receiving server to the sender; it does not automatically prove to the receiver which application sent a request.\n\nProviders may authenticate deliveries using shared secrets, bearer tokens, mutual TLS, or payload signatures. A common approach uses a keyed message authentication code, such as HMAC. Despite sometimes being called a “signature” in product documentation, HMAC uses a shared secret rather than public-key signing.\n\nVerification generally depends on the exact bytes specified by the provider. Parsing and reserializing a JSON body before checking its authentication code can change those bytes and invalidate verification.\n\nReplay and untrusted input\n\nA correctly authenticated request can still be replayed. Signed timestamps, acceptance windows, and tracking previously accepted event identifiers can limit replay, provided those fields are covered by the authentication mechanism.\n\nAuthentication does not make every payload safe to process. Recipients still need schema checks, size limits, authorization checks, and controls against expensive or malicious inputs. Sensitive payloads and credentials can also be exposed through overly detailed logs.\n\nEndpoint registration risks\n\nA sender that accepts arbitrary destination URLs may be exposed to server-side request forgery: an attacker can try to make it contact internal services or other unintended destinations. Endpoint validation, network restrictions, and careful redirect handling address this distinct risk.\n\nEndpoint verification challenges can demonstrate control of a destination, but the guarantees depend on the verification protocol. An unsigned field claiming that a request came from a particular provider is not proof of origin."
    },
    {
      "heading": "Applications and limitations",
      "text": "Webhooks commonly connect payment systems, commerce platforms, customer-management software, monitoring services, and version-control platforms. They can start automated tests, update fulfillment systems, synchronize records, or trigger workflows in serverless computing environments.\n\nTheir principal advantages are low notification latency, compatibility with ordinary web infrastructure, and reduced need for repeated API queries. Their limitations include endpoint availability, delivery failures, duplicated or reordered events, and provider-specific conventions.\n\nWebhook integrations also depend on evolving contracts: event names, payload schemas, retry policies, and authentication formats may change. Explicit versioning, delivery observability, and documented recovery behavior determine how reliably an integration can operate across those changes."
    }
  ],
  "links": [
    "hypertext-transfer-protocol",
    "uniform-resource-locator",
    "application-programming-interface",
    "client-server-model",
    "event-driven-architecture",
    "stream-processing",
    "distributed-computing",
    "idempotence",
    "database-transaction",
    "queue-data-type",
    "authentication",
    "https",
    "transport-layer-security",
    "message-authentication-code",
    "version-control",
    "serverless-computing"
  ],
  "sources": [],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}