feat: event-filtered webhooks, real admin metrics, consistent pagination (closes #192, #193, #196)

[YazarAyobami]

Summary

Implements three Stellar Wave issues in one cohesive backend change:

• Closes feat(webhooks): implement event-filtered webhook delivery (currently every event to every webhook) #192 — Event-filtered webhook delivery: the webhook dispatcher no longer sends every event to every webhook. Deliveries are filtered by each webhook's event-type subscription, retried with exponential backoff, and every attempt (delivered / failed / skipped) is recorded in a delivery log.
• Closes feat(admin): implement real admin metrics (GetMetrics totalVolumeUSD hardcoded to 0) #193 — Real admin metrics: GET /admin/metrics now returns real aggregate metrics instead of a hardcoded totalVolumeUSD: 0, including time-bucketed daily volume series and caching for expensive aggregates.
• Closes fix(api): add consistent pagination metadata to all list endpoints #196 — Consistent pagination metadata: all paginated list responses expose a standard shape including hasMore, and the circle GetRounds / GetPayouts endpoints now accept client page / page_size params.

Changes

#192 — Event-filtered webhook delivery

• webhook/service.go
  • WebhookRegistration now carries Events, IsActive, LastDeliveryAt, and FailureCount; empty event list = subscribe to all events.
  • PostgresRepository was rewritten to match the actual webhooks schema (url, events, secret_hash, is_active, last_delivery_at, failure_count) — the previous queries referenced columns that don't exist in migration 010.
  • DispatchPayload(ctx, eventType, payload, maxRetries) now filters active webhooks by subscription (skipped webhooks get a skipped delivery log entry), retries failures with exponential backoff, updates last_delivery_at / failure_count, and logs each attempt to webhook_deliveries.
  • New repository methods: Delete, UpdateDeliveryOutcome, LogDelivery, ListDeliveries.
• internal/database/migrations/037_create_webhook_deliveries.{up,down}.sql — new delivery-log table with indexes on (webhook_id, created_at) and (event_type, created_at).
• internal/api/handler/webhook_handler.go — registrations now persist through the repository (with a generated HMAC secret) instead of an in-memory map; added GET /webhooks/:id/deliveries (owner-only, paginated) to inspect delivery history.
• internal/api/router.go — registers the new deliveries route.

#193 — Real admin metrics

• New internal/domain/admin package:
  • model.go — Metrics (users, circles, contributions, payouts, active users, 30d new users, contribution/payout volume, total volume, 30d volume) and DailyVolumePoint.
  • repository.go / repository_pg.go — aggregate SQL: totals, active users (activity in the trailing window), volume from confirmed contributions + payouts, and a generate_series-backed per-day volume series.
  • service.go — Service with an in-memory TTL cache (default 60s) for the expensive aggregates; errors are never cached.
• internal/api/handler/admin_handler.go — GetMetrics serves the aggregates (flat response keeps legacy totalUsers/totalCircles/activeCircles/totalVolumeUSD keys), accepts an optional ?days= window (default 30, max 365).
• cmd/api-server/main.go — wires the new service.

#196 — Consistent pagination metadata

• pkg/response/response.go — PaginationMeta and Pagination now include hasMore / has_more computed by NewPaginationMeta (page < totalPages).
• internal/api/handler/circle_handler.go:
  • GetPayouts accepts page / page_size instead of a fixed 1, 50.
  • GetRounds accepts page / page_size (applied to the underlying contribution/payout history queries) and now returns meta; rounds are sorted by round number for a deterministic response.
• All other list endpoints (contributions, payouts, notifications, circles, admin lists, communities) already used pagination.Parse + OKWithMeta, so they automatically inherit the new hasMore field.

Drive-by fix

• internal/api/handler/swap_handler.go — the swap endpoints called response.Error(...) with the wrong signature and didn't compile against the current pkg/response; replaced with the standard response helpers so the repo builds cleanly.

Tests

• webhook/service_test.go — event-type filtering (subscribed vs non-subscribed + skipped log), empty-subscription = all events, retry-until-success with attempt logging, retry exhaustion → failed log, network-error logging; fake repo made thread-safe for the async dispatcher.
• internal/domain/admin/service_test.go — cache hit, cache expiry, per-window cache isolation, error propagation (never cached), default TTL.
• internal/api/handler/admin_handler_test.go — GetMetrics returns real aggregates (non-zero totalVolumeUSD).
• internal/api/handler/circle_pagination_test.go — GetPayouts / GetRounds honor client page/page_size and return hasMore metadata.
• pkg/response/response_test.go — asserts hasMore/has_more presence and edge cases.
• tests/integration/api_routes_test.go — webhook routes now run against an in-memory repo implementing the expanded interface.

Verification

• go build ./... — passes.
• go vet ./... — passes.
• go test ./... -count=1 — all tests pass. (Note: TestConstantTimeCompareTiming is a pre-existing timing flake that only fails under -race, unchanged by this PR.)

Notes

• Volumes are summed in the circle's native currency units (USDC/XLM); totalVolumeUSD is the sum of contribution + payout volume until per-currency conversion rates are wired in (documented in internal/domain/admin/model.go).
• The secret_hash column continues to store the raw HMAC secret so incoming signature verification (POST /webhooks/incoming/:id) keeps working (existing convention, now documented in scanWebhook).

[drips-wave]

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