What is a webhook?

The short version

A webhook is an event notification sent from one application to another over HTTP. You give a service a URL and choose which events matter. When one of those events occurs, the service sends a request—usually an HTTP POST—to that URL with details about the event.

For example, a payment provider can send invoice.payment_failed to your server. Your application can then update the customer’s billing state or notify the support team. The provider initiates the request; your endpoint receives it.

How a webhook works

1. 01

   An event happens

   A customer signs up, a payment fails, or a repository receives a push.

2. 02

   The provider sends a request

   The service sends an HTTP POST with event data to the endpoint URL you configured.

3. 03

   Your endpoint checks it

   Your server verifies the sender, reads the event type, and decides what work to do.

4. 04

   Your application responds

   It returns an HTTP status code, then completes the work or hands it to a background queue.

The sender chooses the request format and headers. GitHub, for example, sends event deliveries as HTTP POST requests and identifies the event with headers such as X-GitHub-Event and X-GitHub-Delivery. Other providers use different headers and payload shapes, so follow each provider’s documentation.

A simple example

Imagine your app lets people subscribe to a product. When a subscription is cancelled, the billing service sends a request to your endpoint with the event and relevant data. Your route might receive a JSON body shaped like this:

{
  "id": "evt_123",
  "type": "subscription.cancelled",
  "data": {
    "customer_id": "cus_456"
  }
}

The real payload is defined by the sender. Your endpoint should validate the request before trusting its contents, handle only event types it understands, and return a successful response after it has safely accepted the delivery.

Webhooks vs. polling

With polling, your application asks a service for updates on a schedule: “Has anything changed?” With a webhook, the service calls your endpoint when a subscribed event occurs. Webhooks can reduce unnecessary repeated requests and let your system react sooner, while polling can be easier when the service does not offer events or your application needs periodic reconciliation.

What to build into a webhook receiver

• Verify the sender. Validate the provider’s signature or secret using its documented algorithm before acting on a payload. Keep secrets out of source control.
• Keep the original body for verification. Some signature schemes are calculated over the raw request bytes, so parsing and serializing JSON first can invalidate the check.
• Handle duplicates safely. A sender may retry when it does not receive a successful response. Record stable event or delivery IDs and make processing idempotent.
• Acknowledge promptly. Validate and enqueue longer work where appropriate, then return the status the provider expects. Check provider-specific response and retry rules.
• Keep delivery records. Log the event ID, timestamp, endpoint, response, and processing result without exposing secrets or unnecessary sensitive payload data.

For specific implementation details, see the official guides for validating GitHub deliveries and verifying Stripe signatures. Signature headers, retry policies, and payload formats are provider-specific.

When should you use a webhook?

Use a webhook when a service can notify your system about events you care about: a new user, a completed payment, a changed issue, or an updated deployment. It is useful when another system needs to react without waiting for a scheduled check. Webhooks do not replace application security, durable queues, or reconciliation; they are one way to deliver event notifications.