Free tools Windows power users keep installed
One-click scans. No signup required.
A webhook is an HTTP request a service sends to your application when a specified event happens. To use one safely, register a reachable HTTPS endpoint, subscribe only to events you need, verify each request using the provider’s signing rules, and acknowledge quickly before processing work in the background. Exact headers, payloads, retry behavior, and deadlines vary by provider.
How a webhook works
A webhook is an event callback. Instead of your application repeatedly asking a service whether anything has changed, the service sends an HTTP request to a URL you register when a subscribed event occurs. Your endpoint receives the request, authenticates it, checks the event type and action, and then handles the work.
As an Amazon Associate I earn from qualifying purchases.
A webhook is an integration pattern, not a universal protocol with one standard security or delivery contract. For example, providers can differ in signature header names, how they encode signatures, which request bytes they sign, how long they wait for a response, and whether or how they retry. Follow the sending provider’s current documentation for those details.
How to set up a webhook endpoint
- Choose the events you need. Subscribe only to events your application uses. GitHub recommends limiting subscriptions to reduce unnecessary work: GitHub’s webhook best practices.
- Make the endpoint reachable over HTTPS. Configure a publicly reachable URL with a valid TLS certificate, and leave certificate verification enabled. DNS resolution, network restrictions, TLS problems, timeouts, or invalid HTTP responses can prevent delivery.
- Configure a provider-specific secret. Use a strong secret when the provider supports signatures. Store it in a secrets manager or protected environment configuration rather than source code or a repository. Do not put API keys or credentials in the webhook URL.
- Verify the request before trusting it. Implement the provider’s signature check before acting on the body or metadata. Preserve the raw request bytes if the provider signs the raw body. Shopify specifically says to run verification middleware before body-parsing middleware: Shopify’s HTTPS webhook guidance.
- Dispatch only recognized events. After verification, inspect the event type and any action field, then route the event to the appropriate handler. GitHub notes event types and actions can evolve, so avoid assuming that every payload will match an old fixed list of fields.
- Respond promptly and move slow work off the request. GitHub recommends returning a 2XX response within 10 seconds. If handling the event could take longer, validate it, place it on a queue, and acknowledge the request rather than holding the connection open during business processing.
- Make processing safe to repeat. Record delivery identifiers where available and make handlers idempotent: processing the same event again should not accidentally repeat a one-time action. Retries can create duplicate deliveries, and events may arrive out of order.
How to test deliveries and diagnose failures
Trigger a real event or a provider-supplied test event, then inspect the provider’s delivery history and the response your endpoint returned. If no delivery appears, check the event subscription and trace whether the provider attempted delivery. GitHub’s troubleshooting guide covers common delivery failures: GitHub webhook troubleshooting.
#1 Best Overall
Connection or delivery failures
- Confirm the registered URL resolves in DNS and is reachable from outside your network.
- Check firewall rules, hosting network restrictions, and any proxy or load balancer in the request path.
- Confirm the TLS certificate is valid and the endpoint returns a valid HTTP response.
- Look for slow handlers or timeouts. Acknowledge promptly and move lengthy work to a background queue.
Signature verification failures
- Confirm that a secret is configured for this endpoint and that your application uses the matching secret.
- Check the exact signature header, algorithm, encoding, and signed bytes specified by the provider.
- Ensure middleware, proxies, or other request handling have not changed the body or signature header before verification.
- For a provider that signs raw request bytes, verify the untouched body before any JSON or form parsing. Shopify documents this middleware ordering for HTTPS webhooks.
GitHub provides a test vector for checking an HMAC-SHA256 implementation: secret It's a Secret to Everybody, payload Hello, World!, expected digest 757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17. It checks the GitHub-style calculation only; it does not replace a test using your configured secret and an actual provider event. See GitHub’s delivery validation documentation.
Provider-specific timing can also matter. Shopify’s API documentation says the shop/redact event can be emitted after a delay following uninstall; do not treat that behavior as a general webhook delivery rule: Shopify webhook API documentation.
Security checks before going live
- Require HTTPS and validate certificates. GitHub recommends keeping SSL verification enabled. If you use an IP allowlist, refresh it periodically because delivery IP addresses can change; GitHub’s metadata endpoint provides the current list. Allowlisting is an additional network control, not a substitute for signature verification. See GitHub’s best practices.
- Authenticate before acting. For GitHub, compute the HMAC using the configured secret and compare it with
X-Hub-Signature-256using a constant-time comparison, not ordinary string equality. Shopify HTTPS webhooks instead use a base64-encoded HMAC inX-Shopify-Hmac-SHA256, based on the app client secret and raw request body. These formats are provider-specific. - Do not trust metadata before verification. Shopify warns that headers such as the topic and shop domain are untrusted until the signature verifies. Treat event fields and routing metadata the same way: authenticate the request before using them to make decisions.
- Protect and scope secrets. Use a high-entropy value, keep it out of code and URLs, and separate configuration by environment where your provider supports it. Limit subscriptions to necessary events and keep work at the network request boundary bounded.
- Plan for retries and ordering. Track delivery IDs where available, deduplicate repeated deliveries, and avoid relying on event arrival order to reconstruct state. Provider delivery logs and manual redelivery can help recover from failures, but their availability and behavior depend on the provider.
What to check in a provider’s webhook documentation
Before integrating a new provider, confirm these details rather than assuming they match another service:
- Which header carries the signature, its encoding and algorithm, and exactly which bytes are signed.
- How secrets are created, stored, rotated, and separated between environments.
- The response deadline, retry schedule, and conditions that trigger redelivery.
- Whether deliveries have unique identifiers, how duplicates are handled, and what ordering or delay guarantees exist.
- Where to inspect delivery logs and whether failed requests can be manually redelivered.
- How to send test events and whether development-mode events have special timing.
GitHub and Shopify illustrate why these are provider-specific questions: their signature headers and representations differ, and their documentation describes distinct delivery and timing behaviors.
Quick Recap
Rank #3
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.
