feat: webhook enhancements and consistency checks

[dannyy2000]

Summary

This PR implements webhook enhancements and admin consistency checks to improve monitoring and data integrity across the platform.

Changes

#660 - Add vault.cancelled webhook event ✅

Context: Subscribers monitoring the funding phase need to know immediately when a vault is cancelled, so they can notify depositors about refunds.

Implementation:

• Added vault.cancelled webhook notification triggered after processing cancel_funding events
• Webhook payload includes contractId and cancelledAt timestamp
• Notification is sent within one tick of the event being indexed

Acceptance Criteria Met:

• ✅ A registered vault.cancelled webhook is called within one tick of the event being indexed

#668 - Add per-vault contract ID filter to webhook subscriptions

Context: A subscriber may only care about events from a specific vault. Without filtering, they receive all vault events and must discard irrelevant ones.

Implementation:

• Added optional contractIds: string[] field to webhooks table
• POST /api/v1/webhooks now accepts contractIds (max 20 addresses; each validated as Stellar C-address)
• NotificationService.notify filters webhooks by contractId before delivery

Acceptance Criteria Met:

• ✅ A webhook with contractIds: ["CA...1"] does not receive events from "CA...2"
• ✅ A webhook with no contractIds receives events from all vaults

#670 - Add GET /api/v1/admin/consistency DB-vs-chain check

Context: The DB can drift from chain state after indexer bugs or RPC outages. A consistency endpoint lets operators detect discrepancies.

Implementation:

• Added GET /api/v1/admin/consistency endpoint accepting contractId query param
• Fetches totalAssets and totalSupply from both DB and chain (via RPC)
• Returns comparison with consistent boolean flag

Acceptance Criteria Met:

• ✅ Returns consistent: false when DB and chain values differ
• ✅ Returns HTTP 500 if the RPC is unreachable

#671 - Add epoch sequence gap detection check

Context: If the indexer skips a ledger range, epoch numbers may have gaps (e.g. epoch 3 and 5 exist but not 4). Gaps indicate missed events.

Implementation:

• Added GET /api/v1/admin/consistency/epochs?contractId=:id endpoint
• Returns { gaps: number[][] } representing missing epoch ranges
• Detects discontinuities in epoch sequences per vault

Acceptance Criteria Met:

• ✅ Returns { gaps: [[4, 4]] } when epoch 4 is missing from sequence 1–5
• ✅ Returns { gaps: [] } for contiguous epoch sequences

Additional Improvements

• Added vault.matured and vault.funded to KNOWN_EVENTS whitelist (already implemented in indexer but missing from webhook validation)

Testing

• Manual testing of webhook delivery with vault cancellation events
• Verified consistency checks with test vaults
• Tested epoch gap detection with manufactured gaps

Closes #660
Closes #668
Closes #670
Closes #671

[drips-wave]

@dannyy2000 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