[feature] X-KeeperHub-RateLimit-* headers on every webhook response

[B2JK-Industry]

Friction

A high-throughput agent fleet hitting KH webhooks can plausibly trip rate limits — but adapter authors today have no in-band signal of how close they are to the limit, and no way to back off proactively. The choices are:

1. Submit blindly + handle 429 reactively (issue [docs+feature] HTTP error code catalog + adapter retry semantics for workflow webhook #52 covers the catalog)
2. Hardcode an external rate cap (defensive but defeats throughput on a quiet workflow)

Neither is right. Adapter callers want headroom telemetry so they can pace correctly under variable load.

Proposed fix

On every webhook response (success + 429), include rate-limit headers:

X-KeeperHub-RateLimit-Limit: 60
X-KeeperHub-RateLimit-Remaining: 47
X-KeeperHub-RateLimit-Reset: 1714478460
X-KeeperHub-RateLimit-Resource: workflow-webhook

Same shape as GitHub / Twitter / many payment APIs. Adapter authors can then implement leaky-bucket or token-bucket clients that respect KH's actual capacity in real time, instead of guessing.

Reference

• GitHub: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limit-http-headers
• RFC 9239 (RateLimit Fields for HTTP, draft): https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers

Context

Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Composes with #52 (error catalog) — together they define the throttling contract.

[suisuss]

Checked this against the live webhook route (app/api/workflows/[workflowId]/webhook/route.ts) and the shared header helper (lib/rate-limit-headers.ts) on keeperhub's staging branch.

Part of the diagnosis holds: the success (200) response carries no rate-limit telemetry today, so an adapter genuinely has no proactive signal on the happy path.

But "no rate-limit headers exist" isn't quite right, and the gap is different from what the proposal assumes. The webhook route's two 429 paths already attach X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset / Retry-After via applyRateLimitHeaders() - one on the org's monthly execution quota (enforceExecutionLimit), one on a global in-flight concurrency cap (checkConcurrencyLimit). Neither of those is a per-caller request-rate limiter in the sense your proposal wants to pace against - a rolling window an adapter can leaky-bucket around. That does exist in the codebase (app/api/execute/_lib/rate-limit.ts, 60 req/60s per API key) and backs /api/execute/* and /simulate, but it is not wired into the webhook route at all. So webhook callers have no per-caller request-rate ceiling today, real or advertised.

That means this isn't "attach headers to an existing counter." Before Remaining can mean what you want it to mean on every response, we need to decide whether the webhook route gets the same per-caller limiter its sibling routes have (worth noting: that limiter is in-memory per pod today, so its effective ceiling scales with replica count - already flagged in the code for a Redis-backed replacement), or whether we'd be relabeling the concurrency/quota counters as "rate limit," which would describe the wrong thing to a client trying to pace request volume. That's a scope decision, not a plumbing change. Marking needs-discussion rather than accepted.

Two more things for whoever picks this up:

1. Header naming: this exact endpoint already ships X-RateLimit-Limit/Remaining/Reset + Retry-After from the shared lib/rate-limit-headers.ts helper, used on about a dozen other routes (execute, MCP, OAuth, billing). Please do not introduce a parallel X-KeeperHub-RateLimit-* namespace - extend the existing convention, including a Resource field on it if per-resource scoping is wanted, since the helper does not carry one yet.

2. This is server response behavior in KeeperHub/keeperhub, not kh CLI behavior - there is nothing webhook-related in this repo's tree, so no PR here would close it. Leaving the issue open as the record of the ask, but the actual fix, once the limiter question above is settled, lands in the app repo.

No duplicate: the only other rate-limit-header hit in this repo is #52, which is about the error catalog and honoring Retry-After on existing 429s, not proactive telemetry on success. Complementary, as you note, not overlapping.

[suisuss]

Following up on my own comment: I left this as work for "whoever picks this up", which is not an answer when the issue has been open since May. I am carrying it.

The open question is unchanged - whether the webhook route gets the same per-caller request-rate limiter its sibling /api/execute/* routes have (which is what would make Remaining mean what you want it to mean), or whether attaching headers to the existing quota and concurrency counters would describe the wrong thing to a client trying to pace request volume. That is bundled with the Redis-backed replacement for the current in-memory limiter, since a per-pod ceiling cannot be advertised honestly.

I am taking that question to the team together with your other four issues from the same batch (#48, #50, #53, #59), because they are all facets of one decision about publishing a stable public contract for this surface, and answering them one at a time is how we would end up with an inconsistent one. I will come back here with where it lands. Nothing is blocked on you.