[REVIEW] api-security: add webhook authenticity and replay evidence gates

[mlodygbelmondo]

Skill Being Reviewed

Skill name: api-security
Skill path: skills/appsec/api-security/

False Positive Analysis

Benign webhook receiver that can be over-reported if reviewers only see a public unauthenticated endpoint:

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.header("stripe-signature");
  const event = stripe.webhooks.constructEvent(
    req.body,
    signature,
    process.env.STRIPE_WEBHOOK_SECRET
  );

  await handleStripeEvent(event.id, event.type, event.data.object);
  res.sendStatus(204);
});

Why this is a false positive risk:

Webhook endpoints are intentionally reachable without user authentication, so a review that only applies the normal API2/API5 authentication checklist can flag them as missing auth. The security decision depends on a different trust model: provider-specific signature verification over the raw request body, timestamp tolerance, replay/idempotency handling, source binding to the expected account/tenant, and event-type allowlisting. The current skill says to inventory downstream dependencies and unsafe consumption, but it does not give reviewers a dedicated way to distinguish an intentionally public signed webhook receiver from an unauthenticated endpoint that accepts forged business events.

Coverage Gaps

Missed variant 1: Webhook accepts forged events because no signature or timestamp is verified

app.post("/webhooks/payment", express.json(), async (req, res) => {
  if (req.body.type === "payment.succeeded") {
    await markInvoicePaid(req.body.data.invoiceId);
  }
  res.json({ received: true });
});

Why it should be caught:

This is API10 unsafe consumption of APIs and often API6 business-flow abuse. The API consumes a third-party event as if it were authoritative, but any caller can synthesize the event. The review checklist currently validates upstream response schemas, TLS, timeouts, redirects, and sanitization, but not inbound provider authenticity for webhook-style APIs.

Missed variant 2: Signature verification is present but broken by parsed-body verification

app.use(express.json());

app.post("/webhooks/stripe", (req, res) => {
  const raw = JSON.stringify(req.body);
  verifyWebhookSignature(raw, req.headers["stripe-signature"]);
  processEvent(req.body);
});

Why it should be caught:

Many webhook providers sign the exact byte stream. Re-serializing parsed JSON can change whitespace, key ordering, encodings, or body bytes, causing teams to disable verification or build a verifier that does not match provider semantics. The skill should require reviewers to verify whether the raw body is preserved until signature verification completes.

Missed variant 3: Replay and duplicate delivery are not handled

Provider event id: evt_123
First delivery: invoice marked paid
Replay within 30 minutes: invoice credited again
Replay next day: still accepted because timestamp is ignored

Why it should be caught:

Valid signatures do not prove freshness or one-time processing. Webhook endpoints should enforce provider timestamp tolerance where available, reject stale signatures, and use provider event IDs or idempotency keys to make processing idempotent. Without this, attackers who obtain a valid signed request through logs, proxies, or test tooling can replay business events.

Missed variant 4: Event is authentic but not bound to the expected account, tenant, or event type

Webhook secret: shared across environments
Event account: connected-account-B
Application tenant: tenant-A
Accepted event types: all
Handler side effect: grants tenant-A subscription

Why it should be caught:

For multi-tenant SaaS, marketplaces, and connected-account integrations, a signature can prove that the provider sent the event but not that the event belongs to the current tenant, environment, connected account, or business flow. The skill should require event-source binding checks: provider account ID, environment, tenant/customer mapping, event type allowlist, object ownership, and secret rotation state.

Edge Cases

• Some providers use HMAC signatures, some use asymmetric signatures, and some use mTLS or signed JWTs; the checklist should be provider-agnostic but require the provider's documented verification method.
• Public webhook endpoints should not require normal end-user sessions, CSRF tokens, or browser cookies; those controls can break legitimate provider delivery.
• Queue-first webhook handlers are safe only if authenticity and freshness are verified before enqueueing side effects, or if the queue message carries verified provenance.
• Retrying providers can deliver duplicates legitimately; idempotency must not reject the first valid retry after a transient failure unless the side effect already succeeded.
• Test-mode and production-mode secrets/events should be isolated so a test event cannot mutate production state.

Remediation Quality

• Fix resolves the vulnerability
• Fix doesn't introduce new security issues
• Fix doesn't break functionality
• Issues found: Add a dedicated webhook/event-source authenticity checklist under API10 and cross-reference API6/API2 where relevant. Require reviewers to capture provider verification method, raw-body handling, timestamp tolerance, replay/idempotency key, event-source/account binding, event type allowlist, environment/tenant mapping, and secret rotation evidence. Add a Not Evaluable outcome when provider docs, webhook secret provenance, or event-source mapping are unavailable.

Comparison to Other Tools

Tool / Framework	Catches this?	Notes
OWASP API Security Top 10 API10	Partial	Covers unsafe consumption of APIs, but the skill needs concrete webhook authenticity and replay checks in its own checklist.
Stripe webhook signature guidance	Yes for Stripe	Requires verifying signatures with the endpoint secret and raw payload semantics, but this is provider-specific and should be generalized.
Slack request signing guidance	Yes for Slack	Uses signing secret plus timestamp freshness to mitigate replay, which is a useful pattern for the skill.
Semgrep / CodeQL	Partial	Can flag missing verifier calls or parsed-body pitfalls in some frameworks, but reviewers still need provider account, tenant, idempotency, and event-type evidence.
API gateway authentication checks	No	Gateways often see webhook endpoints as unauthenticated public routes and cannot prove provider-specific event authenticity or business-object binding.

Overall Assessment

Strengths:

• Strong OWASP API Top 10 coverage with clear BOLA/BFLA distinctions and practical REST/GraphQL examples.
• Good API9 inventory guidance and API10 upstream response validation guidance.
• Useful warning that internal and third-party API data must be treated as untrusted.

Needs improvement:

• Inbound webhook/event-source consumption is not explicitly covered under API10.
• The output format does not require event authenticity, replay, idempotency, or tenant/account binding evidence.
• Public signed webhooks need severity calibration so intentionally unauthenticated receivers are not reported as ordinary missing-auth findings.
• Raw body handling and environment-specific webhook secrets are common implementation pitfalls that should be called out.

Priority recommendations:

1. Add a Webhook and Event Source Authenticity subsection to API10 covering signature/mTLS/JWT verification, raw body preservation, timestamp tolerance, and replay prevention.
2. Add an evidence table with Provider, Verification method, Raw body preserved?, Timestamp tolerance, Replay/idempotency key, Allowed event types, Provider account, Tenant/customer binding, Environment, Secret rotation, and Evidence confidence.
3. Add severity guidance: forged payment/account/security events should be High/Critical; missing idempotency for non-sensitive notifications may be Medium/Low; intentionally public but correctly signed webhooks should not be reported as missing user authentication.

Sources Checked

• OWASP API Security Top 10 2023, API10 Unsafe Consumption of APIs: https://owasp.org/API-Security/editions/2023/en/0xa0-unsafe-consumption-of-apis/
• Stripe webhook signature verification: https://docs.stripe.com/webhooks/signature
• Stripe webhook best practices and duplicate delivery handling: https://docs.stripe.com/webhooks
• Slack verifying requests from Slack: https://api.slack.com/authentication/verifying-requests-from-slack

Bounty Info

• I have read and agree to the CONTRIBUTING.md bounty terms
• Preferred payment method: to be provided privately after acceptance

[auruminternum]

Opened follow-up improvement PR implementing this review: https://github.com/UnitOneAI/SecuritySkills/pull/189\n\nPreferred payment method can be provided privately after acceptance.

[mlodygbelmondo]

Thanks for opening an implementation PR.

For clarity, this issue is my submitted Skill Review under the repository's review bounty terms. Payment details can be provided privately after maintainer acceptance, as noted in the issue body.

[JamesJi79]

REVIEW: api-security PR #183 -- Webhook Authenticity & Replay Evidence Gates

Review Date: 2026-06-03
PR Author: auruminternum
PR Commit: 89fe82a ("Improve API webhook authenticity checks")
Branch: origin/pr/189 (1 commit ahead of main at f4f3374)
Files Changed:

• skills/appsec/api-security/SKILL.md (+15 lines)
• skills/appsec/api-security/api-top10-checklist.md (+86 lines)

---

Summary

This PR adds webhook authenticity, replay protection, and event-source trust boundary coverage to the api-security skill. The current main branch mentions webhooks only as downstream dependencies (SKILL.md step 7) and as an SSRF vector (webhook URL registration). This PR addresses the inbound webhook receiver side — verifying provider-signed events, preventing replay attacks, and binding events to tenants/accounts.

The changes are well-structured, practically grounded (Stripe pattern), and properly map to API10:2023 (Unsafe Consumption of APIs) rather than authentication/authorization categories.

---

Files Reviewed

1. SKILL.md

Change	Assessment
Added "webhook/event-source trust boundaries" to skill description	Correct — reflects expanded scope
New Step 8: "Identify inbound event sources"	Excellent — records provider, verification method, raw-body handling, replay controls, event allowlist, tenant/account binding
New "Trust Boundary Evidence" field in Findings Classification	Strong addition — captures provider verification, timestamp tolerance, replay key, binding, allowlist, confidence
Webhook severity calibration paragraph	Pragmatic — correctly flags payment/account events as High/Critical, idempotency gaps as Medium/Low
Trust Boundary Evidence line in Output Format template	Consistent with the new field
API10:2023 CWE update: added CWE-345, CWE-294	Correct — CWE-345 (Insufficient Verification of Data Authenticity) and CWE-294 (Authentication Bypass by Capture-replay) are precisely the right CWEs
Common Pitfall #7: "Treating signed webhooks as normal unauthenticated routes"	Important distinction — webhook endpoints are intentionally public; review must prove provider authenticity, not browser auth
Added Stripe + Slack webhook references	Authoritative sources

2. api-top10-checklist.md

Change	Assessment
CWE header updated for API10: CWE-345, CWE-294 added	Correct
3 vulnerable patterns added	All realistic and well-chosen
"Webhook and Event Source Authenticity" section	Comprehensive — covers HMAC, raw body preservation, timestamp tolerance, idempotency, binding, environment isolation, secret rotation
Secure pattern (Stripe constructEvent)	Production-quality example with event allowlisting, account binding, tenant binding, idempotency store
Webhook evidence table	Excellent structured format — 11 columns covering every security concern
"Not Evaluable" guidance	Prudent — don't assume safe or unsafe when evidence is missing
3 remediation items	Specific and actionable
5 review checklist items	Complete coverage of provider authenticity, raw bytes, replay protection, binding, environment isolation

---

Findings

FINDING-001 (Minor): csharp-dotnet.md not updated for webhook patterns

Severity: Low
File: skills/appsec/api-security/csharp-dotnet.md

The C#/.NET supplement has no webhook/event-source content. While the PR scope is reasonable (focusing on the two core skill files), the .NET subskill is notably silent on webhook verification. ASP.NET Core webhook handlers have distinct patterns (e.g., UseMiddleware, HttpContext.Request.Body raw read, TimeSpan tolerance for timestamp skew). This is a gap worth noting but not blocking.

Recommendation: Either open a follow-up issue to add .NET webhook patterns, or add a note in the PR body/existing comments acknowledging this.

FINDING-002 (Minor): No GitHub/GitLab webhook examples

Severity: Low
File: skills/appsec/api-security/api-top10-checklist.md

The PR includes Stripe (payment) and Slack (messaging) but omits GitHub and GitLab webhooks, which are extremely common in CI/CD-heavy contexts. These use different verification mechanisms (GitHub uses HMAC-SHA256 over raw body; GitLab uses HMAC via X-Gitlab-Token header matching). Adding a GitHub webhook example would strengthen coverage for developer-facing APIs.

Recommendation: Add a GitHub webhook row to the evidence table or a brief vulnerable/secure pattern for GitHub webhook verification.

FINDING-003 (Info): No mention of webhook retry/at-least-once delivery semantics

Severity: Informational
File: skills/appsec/api-security/api-top10-checklist.md

The PR correctly covers idempotency processing (idempotencyStore.markStarted(event.id)) but doesn't explicitly discuss the at-least-once delivery semantics that providers like Stripe guarantee. A brief note that "providers may retry deliveries; idempotent handling ensures exactly-once side effects even under retry" would reinforce the design rationale.

Recommendation: Add a sentence to the "Webhook and Event Source Authenticity" section explaining why idempotency matters in the context of provider retry behavior.

---

Quality Assessment

Criteria	Score	Notes
Correctness	5/5	All CWEs correctly mapped; patterns are technically accurate
Completeness	4/5	Core webhook content is thorough; .NET subskill and GitHub/GitLab patterns could be follow-ups
Clarity	5/5	Well-written, clear distinguish between outbound API calls and inbound webhook events
Practical Relevance	5/5	Stripe example is the gold standard; evidence table is directly usable in reviews
Consistency	5/5	Consistent with existing SKILL.md structure, findings format, and OWASP mapping
Testability	5/5	Evidence columns and checklist items are directly verifiable in code review

---

Verdict

APPROVED with minor recommendations (FINDING-001, FINDING-002, FINDING-003).

The PR delivers on the issue #183 requirement: it adds comprehensive webhook authenticity and replay evidence gates to the api-security skill. The content is correct, practically grounded, and properly integrated into the existing OWASP API Top 10:2023 framework under API10. The new "Trust Boundary Evidence" field and evidence table provide clear, auditable gates for webhook security review.

The three minor findings (missing .NET patterns, missing GitHub/GitLab examples, missing retry-semantics note) are non-blocking and could be addressed as follow-up issues or a subsequent PR.