15 - Flutter Implementation Guide (Webhooks Module)

• 1. Folder layout
• 2. Models
• 3. Repositories
• 4. Cubits (see 13 for diagrams)
• 5. Key implementation details
• 6. Tests
• 7. Analytics (proposed)
• 8. Roadmap items NOT built (flag in code)

Build order and concrete Flutter implementation notes for the Webhooks module client, on top of 00-shared/11 (app architecture) and 00-shared/06 (state). Reminder: per PRD the native app is post-Phase 1 (PRODUCT_REQUIREMENTS_DOCUMENT.md:144); this guide is the forward-looking build plan.

1. Folder layout

lib/features/webhooks/
  data/
    models/webhook.dart            # webhook.schema.ts:8-30
    models/delivery_log.dart       # webhook-delivery-log.schema.ts:7-39
    repositories/webhook_repository.dart
    repositories/delivery_log_repository.dart
  domain/
    entities/event_types.dart      # vocabulary from event-queue-map.ts:6-43
  presentation/
    cubits/ (WebhookListCubit, WebhookFormCubit, WebhookDetailCubit,
             DeliveryLogListCubit, WebhookActionCubit)
    screens/ (list, form, detail, logs)
    widgets/ (event_picker_chip_field, secret_field, delivery_log_tile,
              metrics_tile, signature_verify_card)

2. Models

class Webhook {
  final String id, name, url, secret;
  final List<String> events;
  final bool enabled;
  final DateTime? lastTriggeredAt; // unused server-side (14 G-2)
  final int failureCount;
  // fromJson maps _id, tenantId, isDeleted, version, createdAt, updatedAt
}

class DeliveryLog {
  final String id, webhookId, eventType, status; // status ∈ pending|success|failed
  final Map<String, dynamic> payload;
  final int? responseCode;
  final String? responseBody;
  final int attemptCount; // always 0 today (14 G-1)
  final DateTime attemptedAt, updatedAt;
  final DateTime? completedAt;
}

3. Repositories

• WebhookRepository: list(), getById(id), create(dto), update(id, dto), delete(id), pause(id), resume(id), test(id), retry(id), metrics(id)
  • one method per endpoint in 12 (no batching; all are single calls).
• DeliveryLogRepository: list(webhookId) → GET /webhooks/:id/logs (≤ 50 rows, webhooks.service.ts:88-93).
• Actions return the { message } envelope; expose message in the cubit state for snackbars ("Test delivery queued", webhooks.controller.ts:69).
• 404 on retry → map to NoFailedDelivery so the dialog can show "Nothing to retry" (webhooks.service.ts:107-108).

4. Cubits (see 13 for diagrams)

1. WebhookListCubit - fetch list; optimistic delete with rollback.
2. WebhookFormCubit - single model for create/edit; dirty-field diff on edit; client validation mirroring 08 §4.
3. WebhookDetailCubit - parallel getById + metrics with independent LoadStates.
4. DeliveryLogListCubit - refresh after test/retry (2-3 s delay), pull to refresh; expose isNewestPending.
5. WebhookActionCubit - pause/resume/test/retry; optimistic enabled flip.

5. Key implementation details

• Event picker: statically shipped vocabulary (event-queue-map.ts:6-43) - no endpoint exists; group by module as in 08 §3; custom chip for free text (exact match, webhook.repository.ts:27).
• Secret field: obscure + generate (client-side Random.secure(), 32 bytes base64url); never cache to disk (13 §7).
• Async actions: after test/retry show "queued" snackbar and navigate to logs; never claim delivery (12 §2 replies).
• Status enum: parse status strictly; unknown values → neutral render (webhook-delivery-log.schema.ts:18-23).
• Code blocks: payload + responseBody in SelectableText monospace with copy; collapse by default on large payloads (06 S6).
• Permission gating: RBAC perms webhook.create/read/update/delete (permissions.constants.ts:89-92) - hide FAB/actions/menus accordingly.

6. Tests

• Unit: model fromJson (incl. enabled default), form validation rules, dirty-diff, status parsing.
• Cubit: list load/delete rollback; retry 404 → NoFailedDelivery; metrics partial failure; action messages surfaced.
• Widget: event picker toggle + min-1 validation; secret reveal; badge rendering per status.
• Integration (00-shared/10): against running API - create → test → poll logs until success; signature verified on an echo receiver.

7. Analytics (proposed)

Wire webhooks.*.* events from 05; no SDK selected yet (00-shared/10 §8).

8. Roadmap items NOT built (flag in code)

• Logs pagination - wait for server (planned), webhooks.service.ts:88-93.
• Inbound receiver screens - wait for public scope (planned), IMPLEMENTATION_PLAN.md:48.
• Secret rotation flow (forward-looking), replay/backfill (planned), event registry endpoint (planned) - all per 12 §7.