[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.