What Is Inside a Webhook Request

A webhook request has three parts you'll see in any app's documentation: a URL, some headers and a payload. Think of a letter. The URL is the address, the headers are the labels on the envelope, and the payload is the letter inside.

The URL

The URL is the web address you gave the sending app. It points at the endpoint, the spot on your system that listens for messages.

Stripe shows the format as https://your-website/your-webhook-endpoint, so a site at example.com with a route called /webhook-handler would use https://example.com/webhook-handler¹. The route name is your choice.

Two details are worth knowing:

• Stripe requires that registered webhook endpoints be publicly accessible HTTPS URLs¹. HTTPS means the connection is encrypted.
• The sending app can't be trusted just because a message arrives at the URL. The signature check below exists for that reason.

The method

A webhook arrives as a POST request. POST is the kind of request that sends data to a server, as opposed to asking for a page. Stripe says its endpoint function must handle POST requests with a JSON payload that includes event information¹.

The headers

HTTP headers let the client and the server pass additional information with a message in a request or response². In a webhook, they describe the message without opening it.

Shopify says every webhook delivery includes headers that describe the topic, source store, API version, and delivery IDs³. Its documentation lists these:

Source: Shopify developer documentation³, checked on 2026-11-14.

GitHub works in a similar way. Its guidance says to check the X-GitHub-Event header to learn what event type was sent⁴.

Header names differ from one app to the next. Always read the sending app's own list.

Two headers that appear everywhere

Content-Type indicates the media type of the resource². For a webhook, it tells you how to read the body, most often as JSON.

A signature header proves the sender. Stripe signs every webhook event by including a signature in the Stripe-Signature header¹. The receiver recomputes the signature with a shared secret and compares. If the two don't match, it should reject the message.

The payload

The payload, or body, is the data about the event. Stripe sends webhook events to your app as a JSON payload that includes event information¹. JSON is a text format for structured data. Reading a webhook payload and JSON shows how to read one.

Some apps let you choose the format. GitHub's guidance says that if you have an option to choose the content type, use JSON⁴.

A typical payload names the event, gives an ID and carries the record that changed. The exact field names depend on the app, so the maker's documentation is the reference.

Reading a request in order

1. Check the signature header against your shared secret.
2. Read the event type, from a header or from the payload.
3. Check the delivery ID so you don't act on the same message twice. Shopify's delivery key exists to deduplicate individual deliveries³.
4. Parse the payload.
5. Reply with a success code. The page on response codes explains what to send.