Harden webhook delivery prune and clarify delivery-log docs

[kentcdodds]

Summary

Small follow-up after #910 / #912 review feedback:

• Scope delivery retention DELETE by user_id as well as endpoint_id
• Document that URL-secret mismatches and rate-limited requests do not write delivery rows
• Move webhook table notes out of the D1 JSON-shadow section in data-storage docs

System recap — extends Inbound webhooks (medium risk)

Mode: recap · Base: main · Head: current branch tip

Classification: extends — retention SQL isolation + architecture doc accuracy for webhooks.

Primitives touched

Primitive	Group	Impact
webhooks	assistant	extends — prune query scopes by user_id; docs match ingress behavior
d1-app-db	storage	composes — same tables, tighter delete predicate

System map

Delivery-log retention deletes now include user_id in both the outer delete and the keep-set subquery.

Legend: green = composes (wiring only) · amber = extended by this PR · red =
new primitive · gray = context (unchanged, included only when an edge crosses
it).

flowchart LR
	webhooks["webhooks<br/>Inbound webhooks"]:::extended
	d1AppDb["d1-app-db<br/>D1 app database"]:::touched
	webhooks -->|"prune deliveries WHERE user_id + endpoint_id"| d1AppDb
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Test plan

• Pre-push unit + e2e
• CI Validate

  

Summary by CodeRabbit

• Bug Fixes
  • Improved webhook delivery retention so cleanup keeps the correct number of recent deliveries for each user and endpoint.
  • URL-secret mismatches now return a 404 without creating delivery records, helping prevent excessive log generation.
  • Delivery records are now created only for authenticated deliveries and rejects identified after authentication.
• Documentation
  • Clarified webhook recording behavior, rejection scenarios, and the fact that delivery records do not contain payload bodies.

[coderabbitai]

📝 Walkthrough

Walkthrough

Webhook documentation now defines when delivery records are written, while retention cleanup scopes retained rows by both user and endpoint.

Changes

Webhook delivery behavior

Layer / File(s)	Summary
Ingress recording rules docs/contributing/architecture/webhooks.md	URL-secret mismatches return 404 without creating delivery rows; authenticated deliveries and post-auth rejects create rows without payload bodies.
Per-user delivery retention packages/worker/src/webhooks/repo.ts	Delivery cleanup now retains rows independently for each (user_id, endpoint_id) pair.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• kentcdodds/kody#910: Related webhook delivery storage and retention behavior.
• kentcdodds/kody#912: Related webhook authentication, rate-limit, and delivery-log behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures both the retention prune hardening and the delivery-log documentation clarification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/kody-webhook-endpoints-primitive-ae09

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-913.kody-a99.workers.dev

Worker: kody-pr-913
D1: kody-pr-913-db
KV: kody-pr-913-oauth-kv

Mocks:

• cloudflare: https://kody-pr-913-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-913-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/contributing/architecture/webhooks.md`:
- Around line 50-51: Update the “Authenticated deliveries” statement in the
webhook architecture documentation to replace “missing declaration” with
“missing verification secret,” preserving the existing delivery-row and
no-payload details.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8ec92159-73f0-4a5f-ba63-2aa74ea4fadf

📥 Commits

Reviewing files that changed from the base of the PR and between f31757b and cc4e652.

📒 Files selected for processing (2)

• docs/contributing/architecture/webhooks.md
• packages/worker/src/webhooks/repo.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Correct the post-auth rejection list.

“Missing declaration” is handled as an earlier 404 with no delivery row in lines 36-39. Remove it here or replace it with the actual post-auth case, such as a missing verification secret.

Suggested wording

-   record a `webhook_deliveries` row (no payload body); ~50 rows
+   record a `webhook_deliveries` row (no payload body); ~50 rows

Replace “missing declaration” in the preceding line with “missing verification secret.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/contributing/architecture/webhooks.md` around lines 50 - 51, Update the
“Authenticated deliveries” statement in the webhook architecture documentation
to replace “missing declaration” with “missing verification secret,” preserving
the existing delivery-row and no-payload details.