Webhook Event

A webhook event is a specific occurrence in an external system that triggers a webhook delivery. When you subscribe to webhooks from a provider like Stripe or GitHub, you're subscribing to events — things that happen in their system that you want to know about. Each event is packaged as an HTTP request and sent to your endpoint with a structured payload describing what happened.

Anatomy of a webhook event

While every provider structures events slightly differently, most webhook events share the same core fields:

• Event type — a string identifying what happened, like payment.succeeded or order.created. This is the field your handler switches on to decide what to do.
• Event ID — a unique identifier for this specific event occurrence. Use this for idempotent processing — if you receive the same event ID twice, skip it.
• Timestamp — when the event occurred in the source system. Not when the webhook was sent (delivery can be delayed by retries or queuing).
• Payload data — the event-specific data: the payment object, the order details, the commit information. This is the body of the webhook request, usually JSON.

Common event types by provider

Most providers use a resource.action naming convention:

Provider	Event type examples
Stripe	payment_intent.succeeded, invoice.paid, customer.subscription.deleted
GitHub	push, pull_request, issues (with action field: opened, closed)
Shopify	orders/create, products/update, customers/delete
Twilio	initiated, ringing, completed (via StatusCallback)
PayPal	PAYMENT.CAPTURE.COMPLETED, BILLING.SUBSCRIPTION.CANCELLED

GitHub is the outlier — it uses the event type as a header (X-GitHub-Event) and includes an action field inside the payload for sub-types. Most other providers put the event type in the JSON body.

Event filtering and subscription

Most providers let you choose which events you receive. There's no reason to receive every event type if you only care about payments:

• Dashboard configuration — Stripe, Shopify, and most SaaS platforms let you check boxes next to the event types you want when setting up a webhook endpoint.
• API configuration — GitHub's webhook API accepts an events array when creating a webhook. You can update it later without re-registering the URL.
• Wildcard subscriptions — some providers support patterns like payment_intent.* to subscribe to all sub-events of a resource type.

Filtering at the source is always better than filtering at the receiver. Fewer unwanted events means less load on your endpoint, fewer signatures to verify, and less noise in your logs.

Event schemas and versioning

Webhook events are an API surface. When a provider changes the structure of an event payload — adding fields, removing fields, changing types — it can break your handler. Good providers handle this carefully:

• Additive changes only — most providers promise to only add new fields, never remove or rename existing ones. Your code should ignore unknown fields rather than failing on them.
• API versioning — Stripe pins webhook payloads to your account's API version. If you're on 2023-10-16, you get events in that version's format even if they've since changed the schema. You opt into new versions explicitly.
• Schema documentation — check the provider's API docs for the exact structure of each event type. Don't reverse-engineer it from sample payloads.

Event ordering and sequencing

Webhook events are delivered via HTTP, which provides no ordering guarantees. Two events that occurred milliseconds apart may arrive in either order, or hours apart if one needed retries. Common scenarios:

• Out-of-order delivery — a subscription.updated event arrives before subscription.created because the first delivery attempt for the create event failed and was retried.
• Duplicate delivery — the provider sent the event, your server processed it, but the response was lost (network issue). The provider retries, and you receive the same event again.
• Delayed delivery — during a provider outage, events queue up and arrive in a burst when the system recovers.

To handle this: use the event ID for deduplication, check the event timestamp against your current state before applying updates, and design your handlers to be idempotent. If your system requires strict ordering, store events and process them in timestamp order rather than processing them on arrival.

FAQ

What is a webhook event?

A webhook event is a specific thing that happens in an external system — like a payment completing, a user signing up, or a file being uploaded — that causes the system to send an HTTP request to your registered webhook URL with the event details.

How do I filter which webhook events I receive?

Most providers let you select event types when configuring your webhook endpoint, either through a dashboard or an API parameter. Subscribe only to the events your application actually needs. If a provider doesn't support filtering, check the event type in your handler and return 200 immediately for events you don't care about.

Can webhook events arrive out of order?

Yes. Webhook delivery is over HTTP with no ordering guarantee. Retries, network delays, and provider-side queuing can all cause events to arrive in a different order than they occurred. Always check the event timestamp and use the event ID for deduplication rather than assuming events arrive sequentially.

Webhook events are delivered as webhook requests with event data in the payload. Verify the signature before trusting the event contents, and process each event idempotently since retries mean the same event can arrive more than once.