[Feature]: Grantfox webhook processor and automatic disbursement flow #142

Feature Request

Problem Statement

Grant approvals and disbursements from Grantfox are currently handled manually or via brittle scripts. There is no reliable webhook processor to consume Grantfox events (approval, payout scheduled, payout completed) and automatically create internal credit records or start payment flows.

Proposed Solution

Create a Grantfox Webhook Processor module that:

• Verifies and authenticates incoming Grantfox webhook signatures.
• Normalizes events (grant_approved, payout_scheduled, payout_completed, grant_revoked) into internal event types.
• Triggers downstream actions: create credit in ledger, enqueue Stellar payment job, and notify project maintainers.
• Provides retry/backoff, dead-letter handling, and an admin UI endpoint to view failed events.

Acceptance criteria:

• Webhook endpoint implemented with signature verification and documented signature scheme.
• Events normalized into a stable internal envelope and persisted for idempotent processing.
• Successful integration test that simulates Grantfox webhook events and results in ledger credits and queued Stellar payments.
• Failed events are retried with exponential backoff and moved to a dead-letter queue after max attempts.

Alternatives Considered

• Polling Grantfox APIs for state (rejected: higher latency and rate limits).
• Using third-party webhook relay (rejected: external dependency and potential vendor lock-in).

Additional Context

This module directly ties Grantfox approvals to Stellar disbursements and will be attractive to Grantfox and Stellar teams since it automates core flows.

Implementation Ideas (Optional)

• Implement an internal EventStore table and use a worker pool (e.g., BullMQ) to process events.
• Provide a small admin endpoint for manual replay of failed events.

Would you be willing to contribute?

• Yes, I'd like to submit a PR for this feature
• I can help with testing
• I can help with documentation
• I'd rather let someone else work on this