feat: on-chain webhook subscription system with HMAC signing (Closes #508)

[LaphoqueRC]

Changes

Implements webhooks for on-chain events as specified in bounty #508.

Core

• Subscribe to events: escrow.locked, escrow.released, reputation.updated, stake.deposited, stake.withdrawn
• HMAC-SHA256 payload signing for delivery verification
• 5-second batch window for efficient delivery
• Exponential backoff retry with 4xx=permanent fail
• Dashboard with delivery stats and retry history
• Test event endpoint + event catalog with payload schemas

Endpoints

• POST /api/onchain-webhooks/register — subscribe (HTTPS-only)
• DELETE /api/onchain-webhooks/{id} — unsubscribe
• GET /api/onchain-webhooks — list subscriptions
• GET /api/onchain-webhooks/{id}/dashboard — delivery stats
• POST /api/onchain-webhooks/{id}/test — send test event
• GET /api/onchain-webhooks/catalog — event type catalog

Database

• Alembic migration 005: onchain_webhook_subscriptions + delivery_logs

Tests

25 pytest test cases across 8 classes:

• Event catalog (3): all types listed, descriptions, constant consistency
• Registration (5): valid, invalid event type, HTTP rejected, empty events, missing URL
• Listing (2): array response, auth required
• Delete (2): nonexistent 404, auth required
• Dashboard (1): nonexistent 404
• Test event (1): nonexistent 404
• HMAC signing (1): SHA256 correctness
• Models (5): Pydantic + SQLAlchemy field validation

---

Wallet: HZV6YPdTeJPjPujWjzsFLLKja91K2Ze78XeY8MeFhfK8

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 20cde0f4-1ce1-4326-ae50-c4b74472b883

📥 Commits

Reviewing files that changed from the base of the PR and between 5a3017b and a514c4b.

📒 Files selected for processing (7)

• backend/alembic/versions/005_onchain_webhooks.py
• backend/app/api/onchain_webhooks.py
• backend/app/main.py
• backend/app/models/onchain_webhook.py
• backend/app/services/onchain_webhook_service.py
• backend/tests/test_onchain_webhooks.py
• docs/onchain-webhooks.md

---

📝 Walkthrough

Walkthrough

This pull request introduces on-chain webhook subscription functionality to the SolFoundry backend. It adds a PostgreSQL migration creating two tables (onchain_webhook_subscriptions and onchain_webhook_delivery_logs), new FastAPI REST endpoints for webhook management, SQLAlchemy ORM models with Pydantic request/response schemas, a service layer implementing subscription registration, event batch dispatch with retry logic and HMAC-SHA256 signing, and delivery tracking. The implementation includes test coverage for API endpoints and models, plus documentation describing supported event types and webhook delivery behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat(webhooks): outbound contributor webhook notification system #729: Implements the contributor-webhooks subsystem that this PR's migration explicitly revises, indicating shared webhook feature infrastructure.

Suggested labels

approved, paid

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: implementing an on-chain webhook subscription system with HMAC signing, and references the associated issue #508.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing the core features, API endpoints, database changes, and test coverage for the on-chain webhook system.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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