The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →An event webhook is a subscription-based HTTP callback. You register an HTTPS URL and the event types you care about; when a matching event occurs, the provider sends an HTTP request containing the event data to your server. Your endpoint verifies the request, acknowledges it quickly, and processes the event safely—usually through a queue.
Event webhook, defined
A webhook is a push notification delivered over HTTP. An event webhook is tied to a particular occurrence—such as a Git push, a pull-request update, an order creation, a deployment, or an app uninstall. Instead of repeatedly asking an API whether anything changed, your application subscribes once and waits for the provider to call it.
GitHub describes webhooks as a way to subscribe to events and automatically receive delivery data when they happen. The term is widely used, but the CloudEvents HTTP Web Hooks specification notes that there is no single formal definition shared by every provider. In practice, the subscription, HTTP delivery, validation, acknowledgement, and retry rules are defined by each provider’s documentation.
How an event webhook works
- Subscribe. In the provider’s dashboard or API, select an endpoint URL and event topics or actions. Store the shared secret or public-key settings required for verification.
- Emit. When a subscribed event occurs, the provider normally sends an HTTP
POSTcontaining a JSON payload. Delivery-specific headers identify the event, topic, signature, timestamp, or API version. - Authenticate and validate. Your server requires HTTPS, verifies the signature with the configured secret, checks the event type and action, validates timestamps or delivery IDs where provided, and parses the documented schema.
- Acknowledge quickly. Return a
2XXresponse within the provider’s deadline. GitHub recommends responding within 10 seconds; work that may take longer should be queued. - Process safely. Persist the delivery identifier, deduplicate repeated deliveries, enqueue expensive work, and make business operations idempotent. If your service was unavailable, use the provider’s redelivery or reconciliation tools.
A minimal request and response
POST /webhooks/provider HTTP/1.1
Host: example.yourapp.com
Content-Type: application/json
X-Provider-Event: order.created
X-Provider-Delivery: 7f3e...
X-Provider-Signature: sha256=...
{"id":"evt_123","type":"order.created","data":{"...":"..."}}HTTP/1.1 204 No ContentThe exact header names, signing algorithm, payload fields, and timeout are provider-specific. For example, Shopify documents HMAC-SHA256 verification plus topic, shop-domain, API-version, webhook-ID, trigger-time, and event-ID headers. GitHub documents event-specific payloads, delivery headers, and a 25 MB payload cap.
#1 Best Overall
Webhook versus polling
| Aspect | Event webhook | Polling |
|---|---|---|
| Direction | Provider pushes when a subscribed event occurs | Your application asks the API at intervals |
| Latency | Usually close to event time, subject to delivery and queue delay | Bound by the polling interval |
| API traffic | No requests when nothing changes | Repeated requests can return no changes |
| Coverage | Limited to events the provider exposes | Can discover state when no webhook exists |
| Recovery | Requires retries, redelivery, and reconciliation planning | Can rediscover current state on the next successful poll |
Webhooks are generally preferable for timely reactions when the provider exposes the event you need. Polling remains useful for backfills, reconciliation after downtime, periodic state checks, and providers that do not offer the required topic. Many robust integrations use both: webhooks for fast notification and an API read to confirm authoritative state.
What is in a webhook payload?
There is no universal payload shape. A delivery commonly includes an event name or topic, an event or resource identifier, the changed object or a reference to retrieve it, actor or sender information, and metadata such as timestamps and API versions. Headers may carry the signature and a delivery ID even when those values are absent from the JSON body.
- GitHub: event-specific POST bodies, sender information, delivery headers, and a documented 25 MB maximum payload.
- Shopify: topic, shop domain, API version, HMAC signature, webhook ID, trigger timestamp, and event ID headers.
Code against the provider’s versioned schema rather than assuming fields from another service. Treat unknown fields as forward-compatible additions and reject only what your contract says is invalid.
Rank #2
Security: verify before you trust
Use HTTPS and certificate verification
Expose an HTTPS endpoint and keep normal certificate verification enabled. Do not disable TLS checks to make a test delivery pass. Restrict inbound access only when the provider publishes stable source ranges; otherwise, signature verification is the primary control.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Verify the signature correctly
Keep the secret outside source control and never put it in the callback URL. Compute the provider’s documented HMAC over the exact raw request body, compare signatures with a constant-time function, and reject malformed or stale requests. Parsing and re-serializing JSON before verification can change whitespace and break a valid signature.
Validate event context
- Check the event type or topic and the action before dispatching business logic.
- Validate the delivery timestamp when supplied to limit replay windows.
- Persist the provider’s delivery ID or event ID and ignore a duplicate that has already been committed.
- Apply authorization rules to the referenced account, shop, repository, or tenant.
- Limit body size and parsing time to reduce denial-of-service risk.
Keep secrets and sensitive data out of logs
Redact signatures, authorization values, customer data, and full payloads unless you have a controlled debugging policy. Log a delivery ID, event type, validation result, processing status, and correlation ID instead.
Rank #3
Reliable processing and retries
Acknowledge, then queue
The HTTP handler should do only the work needed to authenticate, validate the envelope, record an idempotency key, and enqueue a job. Return success after that durable handoff. Sending email, updating several systems, or running a deployment inside the request increases timeout and duplicate risk.
Design idempotent consumers
A retry can contain the same event, and two related events can arrive out of order. Use a unique constraint on the provider delivery ID or event ID, and make side effects conditional on durable state. For example, an “order paid” handler can set a payment state to paid only if it is not already paid, then use an outbox or job table for downstream notifications.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minutePlan for redelivery and downtime
Record failed deliveries and expose metrics for accepted, rejected, queued, completed, and permanently failed jobs. Use the provider’s redelivery feature when available. After an outage, reconcile by listing current resources through the provider API and comparing them with your database; webhook delivery alone should not be your only disaster-recovery source.
Rank #4
- API Security in Action
- Manning Publications
- ABIS BOOK
Respect provider limits
GitHub’s documented acknowledgement recommendation is 10 seconds and its payload cap is 25 MB. Other providers can impose different deadlines, body limits, retry schedules, and maximum attempts. Put those values in configuration and monitor for changes when an API version changes.
Implementing a secure receiver
The following language-neutral flow is the important part; adapt the signature calculation and header names to your provider.
- Read the raw request bytes and enforce a maximum body size.
- Read the signature, event type, timestamp, and delivery ID headers.
- Compute and constant-time-compare the expected signature.
- Reject missing, invalid, or stale authentication before parsing business data.
- Parse JSON and validate the schema, tenant, event type, and action.
- Insert the delivery ID into an idempotency table with a uniqueness constraint.
- Enqueue the event and return a
2XXresponse. - Let a worker perform retries with bounded backoff and a dead-letter path.
async function receive(req, res) {
const raw = await readRawBody(req, { limit: "2mb" });
const signature = req.headers["x-provider-signature"];
const deliveryId = req.headers["x-provider-delivery"];
if (!verifySignature(raw, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).end();
}
if (!deliveryId) return res.status(400).end();
const event = JSON.parse(raw);
if (!isSupportedEvent(event.type, event.action)) {
return res.status(204).end();
}
const inserted = await db.insertDeliveryIfNew(deliveryId, event.type);
if (inserted) await queue.publish({ deliveryId, event });
return res.status(204).end();
}Return a non-2XX status for authentication or malformed-envelope failures so the provider’s documented retry behavior can apply. For an authenticated event that your application intentionally does not handle, a successful response prevents pointless retries.
Best Value
Testing, observability, and operations
- Use a provider test event and verify signatures against the raw body.
- Test duplicate deliveries, out-of-order events, expired timestamps, oversized bodies, malformed JSON, and queue outages.
- Track delivery latency, acknowledgement latency, signature failures, retry count, queue age, dead-letter count, and handler duration.
- Keep a replayable, redacted copy of the envelope or a pointer to it, subject to your privacy and retention rules.
- Document each subscribed topic, schema/API version, secret rotation procedure, and recovery runbook.
Common webhook failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 or signature mismatch | Wrong secret, altered body, wrong encoding, or clock issue | Verify the exact raw bytes, configured secret, algorithm, and timestamp handling. |
| Repeated deliveries | Slow handler, non-2XX response, or lost acknowledgement | Acknowledge after durable enqueue and deduplicate by delivery/event ID. |
| Events appear missing | Subscription filter, disabled endpoint, provider outage, or local downtime | Check subscription status and logs, use redelivery, then reconcile through the API. |
| Duplicate business effects | Handler is not idempotent | Add a uniqueness constraint and make each side effect conditional and repeat-safe. |
| Timeouts | Network, DNS, TLS, or synchronous downstream work | Measure endpoint latency, fix TLS/DNS, and move expensive work to a queue. |
| Unexpected fields or parse errors | Schema/API-version change | Pin supported versions, tolerate additive fields, and test upgrade fixtures. |
When to choose a webhook architecture
Choose event webhooks when a provider offers the events your application needs and near-real-time reaction matters. Combine them with polling or reconciliation when correctness matters more than notification speed, when events can be lost during an outage, or when the provider sends only partial objects. Compare providers on event coverage, schema stability, authentication, retry and redelivery behavior, duplicate identifiers, acknowledgement deadlines, payload limits, API-version policy, observability, and replay tooling.
Or skip the browser setup
If your event-driven workflow also needs website screenshots—for example, to archive a status page after a deployment—you can call ScreenshotNeo instead of maintaining browser automation. It accepts a URL and returns a PNG, JPEG, WebP, or PDF; consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the complete options in the ScreenshotNeo API documentation. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Are webhooks synchronous?
The HTTP delivery is synchronous only long enough for your endpoint to acknowledge it. Reliable systems queue the event and perform business work asynchronously.
Can a webhook call contain the complete updated object?
Sometimes, but providers differ. Treat the payload as provider-defined and retrieve the authoritative object through the API when the event contains only an identifier or partial data.
Should I return success for an event I do not support?
After authenticating the envelope, usually yes: acknowledge an intentionally ignored topic so the provider does not retry it. Return an error for invalid authentication or malformed requests.
Is a webhook a replacement for an API?
No. A webhook notifies you that something happened; the provider API commonly supplies the authoritative record, backfill, and reconciliation operations.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
