feat/Implemented Webhook Listener for Stellar Ledger Events

[samjay8]

Closes #201

🔔 Feature: Webhook Listener for Stellar Ledger Events

Replaces manual status updates with a real-time Soroban event streaming service that automatically updates booking and payment status when on-chain events are detected.

New Files

backend/app/services/webhook_listener.py (234 lines)

• WebhookListenerService — streams contract events via SorobanServer.stream()
• Filters for EngagementInitializedEvent and ReclaimedEvent by contract address
• Redis cursor tracking with TTL for idempotent processing
• Async processing pipeline with error handling and retry logic

backend/app/services/event_handler.py (138 lines)

• Maps on-chain events to database state changes
• EngagementInitializedEvent → Booking IN_PROGRESS
• ReclaimedEvent → Booking PENDING, Payment FAILED
• Enforces state machine rules throughout

backend/app/db/migrations/004_add_events_table.py (65 lines)

• events table for tracking processed on-chain events
• Indexed on contract_address, topic, and ledger_sequence
• Includes processing status, retry count, and audit timestamps

Modified Files

• backend/app/core/config.py — added WEBHOOK_LISTENER_ENABLED, EVENT_STREAM_INTERVAL (5s), EVENT_CURSOR_TTL (24h)
• backend/app/api/v1/endpoints/health.py — comprehensive health checks (DB, Redis, Soroban, Webhook); added POST /api/v1/webhook/listener
• backend/app/main.py — registered webhook listener route; updated root endpoint

Acceptance Criteria

✅ SorobanServer.stream() used for real-time event streaming
✅ EngagementInitializedEvent and ReclaimedEvent handled
✅ Booking/payment status updated automatically on event detection
✅ Idempotent processing via Redis cursor tracking

[drips-wave]

@samjay8 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[gabito1451]

@samjay8 you might want to look in to CI

[samjay8]

@samjay8 you might want to look in to CI

I don't think it's from my end.

[samjay8]

@gabito1451, I guess this is from your end. I just worked on it again, yet the CI still failed.