What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Secure license-fulfillment webhooks in layers: verify the sender’s signature against the exact request bytes, check freshness if the provider signs a timestamp, persistently deduplicate the authenticated delivery, and make the license grant idempotent. A valid HMAC helps establish that a request was created by someone with the shared secret and was not altered; by itself, it does not stop someone from sending the same valid request again.
What signature verification does—and what it does not do
A webhook signature lets a receiver check that the signed data matches a message produced with the expected secret and has not changed in transit. For example, GitHub documents HMAC-SHA256 signatures in the X-Hub-Signature-256 header and recommends comparing the expected and supplied signatures in constant time. Its documentation says, “Never use a plain == operator.” See GitHub’s webhook validation guidance.
As an Amazon Associate I earn from qualifying purchases.
That check does not prove a delivery is new. As GitHub’s webhook best practices put it, “In a replay attack, a bad actor intercepts a webhook delivery and re-sends it.” A captured, correctly signed request can still pass signature verification if it is submitted again. Preventing duplicate license effects therefore requires freshness checks where the provider supports them, durable event deduplication, and idempotent fulfillment.
Do not assume every sender uses GitHub’s header, algorithm, or delivery behavior. Each provider defines its own signed message format, identifier, timestamp rules, and retry expectations.
Process each delivery in a secure order
- Constrain the endpoint. Accept only the HTTP method and route intended for the integration, set a request-size limit appropriate to the expected event, and serve the endpoint over HTTPS. Keep TLS certificate verification enabled. GitHub recommends HTTPS and SSL verification in its webhook best practices.
- Capture the original request. Preserve the body as raw bytes along with the headers needed by the provider’s verification scheme. Verify before JSON parsing, re-serializing, normalizing line endings, or otherwise transforming the body. A parser, middleware, proxy, or load balancer that changes signed bytes can make a legitimate signature fail—or cause your verifier to check something different from what the sender signed.
- Select the right provider verifier. Choose the algorithm, secret, signed fields, and signature-header parser from the integration’s configured sender, not from an untrusted payload field. Reject malformed, missing, or invalid signatures before event data reaches license logic. For a new GitHub integration, use its documented
X-Hub-Signature-256HMAC-SHA256 format rather than substituting the legacy SHA-1 header. - Compare safely. Compute the expected signature in the format the provider specifies, validate the supplied header’s syntax and length, then use a constant-time comparison provided by your language or cryptographic library. Do not compare secret values or signature strings with an ordinary equality operator.
- Check freshness when the signed protocol supports it. If the provider includes a timestamp in the signed material, reject requests outside a tolerance you set to match that provider’s documented rules and your delivery conditions. The OWASP Webhook Security Guidelines are currently a draft and give ±5 minutes as an example, not a universal tolerance. A timestamp that is not covered by the signature can be altered, and even a valid timestamp only narrows the replay window; it does not prevent a duplicate inside that window.
- Validate the event’s meaning. After authentication, parse the body and allow only the event types and actions your integration expects. Confirm that the event maps to a known order, customer, or entitlement under your own records before granting a license. A valid signature authenticates the message; it does not mean every signed event should trigger the same business action.
- Claim the delivery durably. Use the provider’s stable event or delivery identifier, when available, as a key in persistent storage. Claim it atomically after authentication and freshness checks. If it has already been claimed or processed, do not repeat fulfillment; acknowledge the duplicate according to the sender’s delivery rules.
- Fulfill through an idempotent workflow. Apply the grant so that retries and concurrent workers cannot create a second license for the same purchase or entitlement. Persist enough state to resume safely if processing fails partway through.
Make deduplication and license issuance survive retries
Webhook delivery is often retried after timeouts or failures, so duplicate handling is normal operations work as well as a defense against replay. OWASP’s draft guidance and GitHub’s best practices support deduplication and safe handling of repeated deliveries. Applied to license issuance, the key outcome is that one purchase must not yield multiple grants merely because the sender retried or two workers received the same event at once.
- Enforce uniqueness in durable storage. Store the provider and relevant account or endpoint scope with the event ID, and enforce uniqueness at the database level. An in-memory set or a check followed later by an insert is not enough: concurrent requests can both pass the check before either records the event.
- Protect the business effect too. Deduplicating delivery IDs handles repeats of the same event, but a provider could represent the same underlying purchase with a different event ID. Also enforce a business-level uniqueness rule for the entitlement or purchase that should produce the license.
- Coordinate state changes. A robust design records the authenticated event and the work to be performed durably, then lets a worker process it. Where database transactions are available, an inbox/outbox pattern can commit the event claim and queued work together. Make the grant operation safe to retry after a crash, including when the license was created but completion status was not saved.
- Keep deduplication state long enough. Retain event claims for at least the period in which provider redeliveries and relevant replays remain possible under your integration’s rules. A permanent business-level uniqueness constraint on the entitlement can protect against old deliveries even after operational event records are archived.
- Handle missing identifiers deliberately. If the provider does not supply a stable event ID, do not silently treat a payload hash as a universal substitute; distinct legitimate events may have identical bodies. Use the provider’s documented identity semantics or a business key appropriate to the operation.
Protect secrets, logs, and the delivery path
A shared-secret signature depends on keeping the secret private: anyone who obtains it may be able to create messages that pass verification. Use a high-entropy secret, store it in a secure secret-management mechanism rather than source code, and follow the provider’s supported rotation process. Do not write the secret, signature key material, or full sensitive payloads to application logs. GitHub’s recommendations for a high-entropy secret and secure handling are in its validation documentation.
Rank #2
Log enough operational context to investigate failures without exposing sensitive data: provider, event or delivery ID, event type, processing state, and a concise failure reason. Restrict access to those logs and apply retention appropriate to the data they contain.
Free tools Windows power users keep installed
One-click scans. No signup required.
Acknowledge safely and recover from failures
Do not hold a provider connection open while performing slow fulfillment if the provider expects a quick response. First verify and durably record the event and its work; then acknowledge and process asynchronously where the provider’s protocol allows it. Acknowledge only after the event is safely accepted, so a process crash cannot turn a successful response into lost license work.
Deadlines and retry rules are provider-specific. For GitHub, the receiver should respond with a 2XX within 10 seconds; GitHub suggests asynchronous processing when needed. That deadline is GitHub’s rule, not a general webhook timeout. Follow the sender’s current delivery guidance, and provide a controlled way to retry failed work without bypassing deduplication or idempotency.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Check these details before integrating another provider
Before implementing a verifier for a license vendor or payment provider, confirm these points in that sender’s current official documentation; the rules should not be inferred from GitHub’s protocol:
- The exact bytes or canonical representation covered by the signature, including any required encoding.
- The algorithm, signature header format, and correct constant-time comparison approach.
- Whether a timestamp is included in the signed data, how its age is evaluated, and the provider’s stated tolerance.
- Which event or delivery identifier remains stable across retries or manual redelivery.
- The acknowledgment deadline, retry schedule, and required response behavior.
- How secrets are stored, changed, or rotated, and whether an official SDK requires access to the raw request body.
Use the provider’s documented semantics to build its adapter, then keep the shared processing guarantees—authenticate first, reject stale signed requests where applicable, claim deliveries durably, and make license effects idempotent—at the center of the workflow.
Recommended Free Tools
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.
