[chiragjangiir]

Summary

Resolves #674 by introducing configurable webhook payload size limits, pre-buffering stream defenses, safe truncation and fail-closed rejection policies, structured error responses, and end-to-end boundary tests.

Root Cause / Context

Webhook endpoints lacked payload byte-level bounds and pre-buffering enforcement, creating risks of unbounded memory consumption or inconsistent error semantics when receiving oversized payloads.

Changes

• Configuration:
  • Added WEBHOOK_MAX_PAYLOAD_BYTES (default: 256 KB) and WEBHOOK_OVERSIZED_POLICY (reject [default] or truncate) to Config in app/config.py and documented in .env.example.
• Validation & Policy Service (app/services/webhook_payloads.py):
  • Implemented read_webhook_stream with pre-buffering enforcement: evaluates Content-Length headers before body reads, and aborts chunked streams exceeding limits to prevent excessive memory buffering.
  • Implemented enforce_payload_size:
    • Under reject policy: fails closed with HTTP 413 and structured error details (payload_too_large).
    • Under truncate policy: safely truncates voluminous non-essential fields (diff, raw, content, findings, etc.) while ensuring core immutable envelope fields (id, event_type, timestamp, workspace_id) are never corrupted; adds explicit _truncated: True metadata.
  • Returns consistent structured errors matching repository conventions: 400 (malformed_payload, empty_payload), 401 (unauthorized), 413 (payload_too_large), 422 (invalid_payload).
  • Added @require_webhook_payload_limit view decorator.
• Endpoints (app/webhooks/):
  • Registered webhooks blueprint with GET /api/webhooks/policy and POST /api/webhooks/events.
• Documentation (docs/webhooks.md):
  • Documented payload limits, oversized policies, pre-buffering enforcement, and structured error codes.
• Automated Tests (tests/test_webhook_payload_limits.py):
  • 17 unit and boundary integration tests covering under-limit, at-limit, over-limit (rejection), over-limit (safe truncation), required field immutability, stream chunk aborts, pre-buffering headers, malformed JSON, missing fields, authentication, and sanitized logging.

Verification

• pytest tests/test_webhook_payload_limits.py tests/test_event_wiring.py tests/test_events.py -v: 54/54 passed.
• ruff check .: All checks passed.
• black --check .: All checks passed.