Webhook Security Testing: Signatures, Replay and Evidence

Webhook security best practices should produce evidence that an integration accepts authentic events, handles repeated deliveries safely, and limits the business actions those events can trigger. A signature check alone cannot prove that a refund happens once, a tenant boundary holds, or an investigator can reconstruct a disputed deployment.

For AppSec and integration engineers, the assessment unit is the complete event path: provider, public receiver, queue, worker, downstream API, and resulting business record. For the CTO sponsoring the work, the decision is whether that path is safe enough to connect to payments, billing, account permissions, or CI automation.

This guide provides a control assessment and test matrix for that decision. The scenarios are illustrative test designs, not client findings or claims about a named provider.

Define the webhook threat model and business boundary

Start with an integration inventory. Record each provider, environment, endpoint, signing mechanism, subscribed event type, owner, and downstream action. Include webhook registration and secret-management interfaces, not just the receiver. Identify who can change callback destinations, enable events, rotate keys, or request redelivery.

Distinguish inbound events from outbound callbacks. An inbound payload can introduce untrusted values into a worker. An outbound registration feature can make your infrastructure connect to a destination supplied by a customer. Both require testing, but they cross different trust boundaries.

Write a business invariant for each sensitive workflow. For example: one authorized payment transition can create one entitlement for the correct customer. A successful HTTP response is not the invariant. The evidence must reach the entitlement record and show that unrelated accounts remain unchanged.

Agree on sandbox accounts, synthetic objects, maximum concurrency, cleanup, and stop conditions. Use test destinations under your control for network tests. Reproduce financial and deployment effects through approved test systems rather than triggering live transactions.

Use a webhook security testing matrix

Run a valid control event before each negative test. Keep fixtures isolated so an earlier delivery cannot accidentally explain a later rejection. Record the deployed version, configuration, provider contract, and expected business result alongside each test.

Test signature verification against the provider contract

Use the provider's documented verifier or maintained SDK where available. Confirm the exact signed message, header grammar, encoding, algorithm, and key selection rules. A generic timestamp-plus-body HMAC example is not compatible with every provider.

For schemes that sign the request body, preserve the bytes used by verification before parsing or normalization changes them. Test the deployed middleware chain, including gateways and decompression behavior. Reformatting JSON can preserve its meaning while changing its signature input.

GitHub's verification guidance specifies an HMAC signature in X-Hub-Signature-256 and recommends constant-time comparison. Its documented format is a provider-specific example, not a universal webhook protocol.

Signature verification testing should cover empty and malformed headers, unsupported signature versions, truncated digests, incorrect secret selection, and legitimate rotation overlap. Reject verification failures before creating durable event-processing state. Otherwise, an unauthenticated request could reserve an event ID and suppress the genuine delivery.

Check which metadata is actually authenticated. A valid body signature does not automatically authenticate an arbitrary delivery-ID or tenant header. Never let a changed unsigned header select a different customer or bypass a duplicate guard. Bind the integration to trusted configuration and validate event identity according to the provider's contract.

For signing-key rotation, define the allowed overlap, expiry, and emergency-revocation procedure per integration. Test both sides of the cutover on every receiver instance, including delayed deliveries. Keep test and production secrets separate, and log the internal key version used for verification without recording the secret. A previous key should stop working when policy says it has expired.

Separate replay prevention from event idempotency

Webhook replay prevention addresses reuse of a captured authentic message. Event idempotency addresses repeated processing of the same logical event or business operation. A legitimate retry can resemble a malicious replay at the transport layer. The receiver must preserve the business invariant without treating every repeat as an incident.

For providers with signed delivery timestamps, test both age and future skew against a documented tolerance. An unsigned timestamp cannot establish freshness. Stripe documents signed timestamps, a default five-minute verification tolerance, and renewed signatures on retries. These semantics should not be imposed on integrations that use a different scheme.

When a provider has no signed freshness mechanism, document the limitation and strengthen durable duplicate controls, key protection, and monitoring. Do not invent a timestamp header and assume it prevents captured-message reuse.

Choose a deduplication namespace that includes provider, integration or account, environment, and authenticated event identity. Keep delivery-attempt identifiers separate from logical event IDs. Define retention around documented retry behavior, manual redelivery, operational recovery, and the useful lifetime of the business action. A universal one-day cache entry is not a defensible policy.

Test whether one logical operation can arrive under different event IDs. Apply a business-level uniqueness rule where appropriate, such as a permitted transition for a particular invoice. Avoid collapsing every update to the same object into one event: subsequent legitimate updates may be distinct operations.

Prove duplicate safety through worker crashes and retries

A successful atomic cache insertion only proves that one claimant won that insertion. It does not prove that the business operation completed or that a worker can recover. A crash after marking an event as seen can lose work; a crash after a downstream action can repeat it.

Review durable states such as received, processing, completed, and recoverable failure. Claim work atomically, define lease expiry and recovery ownership, and retain completion evidence. For local mutations, use transactions and uniqueness constraints that protect the business invariant. For external actions, use the downstream API's supported idempotency mechanism and reconcile ambiguous outcomes.

Acknowledge delivery only after the event is durably accepted for processing under the chosen architecture. If persistence is unavailable, return the failure response required by the provider's recovery contract. Do not return success while silently dropping an event. For an authenticated duplicate already completed or durably owned, a successful acknowledgement can be appropriate without repeating work.

Inject a worker interruption after claim, after queue publication, immediately before the business write, and after the external response but before local completion. Re-run the event and inspect final records. A report should state exactly which boundaries were exercised rather than claim universal exactly-once delivery.

Validate tenant ownership and business side effects

Authenticity establishes that a sender with the signing authority produced the message. Your application still decides whether its content is authorized to change a particular object. Resolve tenant ownership through the integration configuration and server-side relationships, then check the target object's tenant again inside the worker.

Use two isolated test tenants and deliberately mismatched customer, invoice, repository, or project identifiers. Verify that the handler cannot route an authentic event for one integration into another tenant's resources. Extend the test into background jobs and administrative recovery tools using a tenant and object authorization matrix.

Exercise valid events in an invalid sequence: cancellation before activation, completion after revocation, or a delayed update after a newer business state. Define how the worker reconciles uncertainty with authoritative records. Provider timestamps alone may not encode the ordering guarantees your business needs.

Also constrain downstream authority. A billing listener should not inherit deployment privileges because both run in the same worker pool. Include integration credentials, permission changes, and revocation behavior in SaaS token lifecycle testing when those credentials can authorize further actions.

Bound payload parsing and outbound network access

After authenticity checks, validate supported event types and the fields the workflow consumes. Define compatibility for provider schema changes explicitly. Reject invalid required fields, but do not assume every new optional provider field is malicious. Normalize accepted data into a small internal representation.

Enforce actual bytes read, supported content types, parser limits, processing time, and decompressed size where applicable. A client-supplied Content-Length value is not sufficient enforcement. Test malformed JSON and ambiguous duplicate keys. Assess XML entity handling or multipart limits only if those formats are actually accepted. OWASP's input-validation guidance supports validating structure and meaning at the boundary.

Where a payload or registration field causes a server-side fetch, test the complete connection path. A hostname check followed by an unrestricted fetch can fail through redirects, address-family differences, or resolution changes. Apply destination policy at connection time, validate every permitted redirect, and enforce network egress restrictions. Use OWASP's SSRF prevention guidance to inform the implementation review.

HTTPS, supported mTLS, and maintained provider IP ranges can add protection. Validate proxy trust before using forwarded addresses for enforcement. Keep signature and authorization requirements mandatory even when a risk score is low. Bound queue growth and worker cost using authenticated integration identity where available, with edge limits for unauthenticated traffic.

Capture webhook incident evidence across the event path

Webhook incident evidence should answer four questions: what arrived, which controls decided its disposition, what work ran, and which business record changed. Log request correlation, trusted integration identity, verification result, reason code, policy version, event identity, processing attempt, and the final business reference.

Separate claimed provider times from receiver and worker times. Record clock synchronization health and identify the source of client-address metadata. Correlate delivery attempts to the same logical event without relying on attacker-controlled values as the sole join key.

A payload hash can help compare retained bytes, but does not independently establish sender authenticity or prove that a log was never altered. Protect the evidence store, record access and collection, and preserve an appropriate custody history. Restrict raw payload retention to justified needs with encryption, access controls, and a retention schedule.

Exclude signing secrets, access tokens, and unnecessary personal data from routine logs. Test that rejected requests cannot inject misleading log entries. OWASP's logging guidance provides the broader safeguards; our breach timeline and evidence workflow explains how to connect records during an investigation.

Map findings to OWASP without overstating coverage

Use risk categories to explain findings and versioned verification requirements to define checks. These mappings are assessment interpretations, not an OWASP webhook certification or a claim that one matrix covers the entire standard.

• API2:2023 Broken Authentication: failures in sender authentication or signing-secret handling.
• API6:2023 Unrestricted Access to Sensitive Business Flows: repeated or automated abuse of sensitive operations.
• API7:2023 Server Side Request Forgery: unsafe server-side connections triggered by event data or destinations.
• API10:2023 Unsafe Consumption of APIs: insufficient validation of integrated third-party data.

For ASVS 5.0.0, select applicable requirements for validation, API security, authorization, cryptography, configuration, and logging from the versioned release. Put exact requirement IDs into the agreed test plan after checking their wording. Tenant isolation and resource exhaustion may also require API1 and API4 coverage beyond the four categories above.

Scope webhook and API integration testing

A new webhook provider, signing-key rotation, or duplicate side-effect incident is a practical trigger for assessment. Bring endpoint and event inventories, provider verification documents, sandbox credentials, worker architecture, integration permissions, and a sample evidence trail.

Scope and effort depend on provider-specific signature schemes, tenant boundaries, event families, asynchronous components, and recovery scenarios. Ask for a coverage matrix, reproducible sanitized findings, business-impact evidence, remediation priorities, and targeted retesting. Reserve time for worker and downstream verification rather than allocating the entire engagement to HTTP payloads.

Pentest Testing Corp's API penetration testing services provide the route to scope this work. Request a webhook and API integration assessment covering sender authenticity, replay controls, duplicate processing, tenant boundaries, and evidence continuity. If suspicious deliveries have already caused harm, use digital forensic analysis and incident response to scope preservation and investigation.