Skip to content

WEBHOOK_IMPLEMENTATION.md

Latest commit

 

History

History
386 lines (293 loc) · 9.74 KB

WEBHOOK_IMPLEMENTATION.md

File metadata and controls

386 lines (293 loc) · 9.74 KB

Webhook Event Logs Viewer Implementation

Overview

A comprehensive admin interface for monitoring webhook deliveries, debugging integration issues, and retrying failed events.

Features Implemented

✅ Core Requirements

  • Events Table: Displays timestamp, event type, status, HTTP status, payload preview, and retry count
  • Status Filtering: Filter by success, failed, pending, or retrying status
  • Event Type Filtering: Filter by specific webhook event types
  • Retry Functionality: Retry failed webhooks with visual feedback
  • JSON Viewer: Expandable modal with formatted JSON payload and response
  • Real-time Updates: Optional live updates for webhook events
  • Responsive Design: Mobile, tablet, and desktop support
  • Accessibility: WCAG 2.1 AA compliant with proper ARIA labels and keyboard navigation
  • TypeScript Strict: No any types used throughout the implementation

File Structure

app/
├── admin/
│   └── webhooks/
│       └── page.tsx                    # Main admin webhooks page
└── api/
    └── webhooks/
        ├── events/
        │   └── route.ts                # GET endpoint for fetching events
        └── retry/
            └── route.ts                # POST endpoint for retrying webhooks

components/
├── atoms/
│   └── WebhookStatusBadge.tsx          # Status badge with icons
├── molecules/
│   ├── WebhookEventRow/
│   │   ├── WebhookEventRow.tsx         # Table row component
│   │   └── index.ts
│   ├── WebhookDetailsModal/
│   │   ├── WebhookDetailsModal.tsx     # Full event details modal
│   │   └── index.ts
│   └── WebhookFilterBar/
│       ├── WebhookFilterBar.tsx        # Filter controls
│       └── index.ts
└── organisms/
    └── WebhookEventLogsViewer/
        ├── WebhookEventLogsViewer.tsx  # Main viewer component
        └── index.ts

lib/
├── types/
│   └── webhook.ts                      # TypeScript type definitions
├── api/
│   └── mock/
│       └── webhookEvents.ts            # Mock data (10 sample events)
└── webhook/
    └── webhookFilters.ts               # Filtering and sorting logic

Type Definitions

WebhookEvent

interface WebhookEvent {
  id: string;
  timestamp: string;
  eventType: WebhookEventType;
  status: WebhookEventStatus;
  endpoint: string;
  httpStatus: number | null;
  payload: WebhookEventPayload;
  response: string | null;
  errorMessage: string | null;
  retryCount: number;
  maxRetries: number;
  nextRetryAt: string | null;
}

Event Types

  • credit.issued
  • credit.retired
  • credit.transferred
  • project.approved
  • project.updated
  • transaction.completed
  • transaction.failed
  • wallet.created
  • payment.received
  • payment.failed

Status Types

  • success - Event delivered successfully
  • failed - Event delivery failed
  • pending - Event pending delivery
  • retrying - Event being retried

Components

WebhookEventLogsViewer (Organism)

Main container component that orchestrates the entire webhook logs interface.

Props:

  • events: WebhookEvent[] - Array of webhook events
  • onRetryEvent?: (eventId: string) => Promise<void> - Callback for retry action
  • enableRealtime?: boolean - Enable real-time updates

Features:

  • State management for filters, selection, and modal
  • Real-time event updates (simulated)
  • Optimistic UI updates on retry
  • Empty state handling

WebhookEventRow (Molecule)

Individual table row displaying webhook event summary.

Props:

  • event: WebhookEvent - Event data
  • onRetry: (eventId: string) => void - Retry callback
  • onViewDetails: (event: WebhookEvent) => void - View details callback
  • isRetrying?: boolean - Loading state for retry button

Features:

  • Payload preview (first 3 keys)
  • Conditional retry button (only for failed events)
  • Color-coded HTTP status
  • Accessible table structure

WebhookDetailsModal (Molecule)

Full-screen modal displaying complete event details.

Props:

  • isOpen: boolean - Modal visibility
  • event: WebhookEvent | null - Event to display
  • onClose: () => void - Close callback

Features:

  • Formatted JSON display with syntax highlighting
  • Copy to clipboard functionality
  • Metadata grid layout
  • Error message highlighting
  • Keyboard accessible (ESC to close)

WebhookFilterBar (Molecule)

Filter and search controls for the events table.

Props:

  • filters: WebhookFilterState - Current filter state
  • onFilterChange: (filters: Partial<WebhookFilterState>) => void - Filter change callback
  • eventTypes: WebhookEventType[] - Available event types
  • resultCount: number - Filtered results count
  • totalCount: number - Total events count

Features:

  • Search by ID, event type, endpoint, or error
  • Status dropdown filter
  • Event type dropdown filter
  • Sort by timestamp, event type, or status
  • Sort order toggle (asc/desc)
  • Results count display

WebhookStatusBadge (Atom)

Visual status indicator with icon and color coding.

Props:

  • status: WebhookEventStatus - Event status
  • className?: string - Additional CSS classes
  • size?: 'sm' | 'md' - Badge size

Features:

  • Status-specific icons (✓, ✕, ○, ↻)
  • Color-coded variants
  • Tooltip with description

API Routes

GET /api/webhooks/events

Fetch webhook events with optional filtering.

Query Parameters:

  • status?: string - Filter by status
  • eventType?: string - Filter by event type
  • limit?: number - Limit results (default: 100)

Response:

{
  "events": WebhookEvent[],
  "total": number,
  "timestamp": string
}

POST /api/webhooks/retry

Retry a failed webhook event.

Request Body:

{
  "eventId": string
}

Response:

{
  "success": boolean,
  "eventId": string,
  "message": string,
  "status": string
}

Accessibility Features

  • Semantic HTML: Proper table structure with <thead>, <tbody>, <th>, <td>
  • ARIA Labels: All interactive elements have descriptive labels
  • Keyboard Navigation: Full keyboard support for all actions
  • Focus Management: Modal traps focus, returns focus on close
  • Screen Reader Support: Status announcements and descriptions
  • Color Contrast: WCAG AA compliant color combinations
  • Responsive Tables: Horizontal scroll on mobile with sticky headers

Responsive Design

Mobile (< 640px)

  • Stacked filter controls
  • Horizontal scrolling table
  • Full-width modal
  • Touch-friendly button sizes

Tablet (640px - 1024px)

  • 2-column filter grid
  • Optimized table layout
  • Adjusted modal width

Desktop (> 1024px)

  • 4-column filter grid
  • Full table visibility
  • Large modal with side-by-side layout

Real-time Updates

When enableRealtime={true}:

  • Polls for status changes every 5 seconds
  • Updates retrying events to success/failed
  • Visual "Live" indicator with pulsing dot
  • Optimistic UI updates on user actions

Mock Data

10 sample webhook events covering all event types and statuses:

  • 5 successful events
  • 2 failed events
  • 1 retrying event
  • 1 pending event
  • 1 event with no HTTP status

Integration Guide

1. Add to Admin Navigation

<Link href="/admin/webhooks">Webhook Logs</Link>

2. Replace Mock Data with Real API

// In app/admin/webhooks/page.tsx
const { data } = await fetch('/api/webhooks/events');

<WebhookEventLogsViewer
  events={data.events}
  onRetryEvent={async (eventId) => {
    await fetch('/api/webhooks/retry', {
      method: 'POST',
      body: JSON.stringify({ eventId }),
    });
  }}
  enableRealtime={true}
/>;

3. Implement Backend Logic

  • Connect to database for event storage
  • Implement webhook delivery system
  • Add retry queue with exponential backoff
  • Set up real-time event streaming (WebSocket/SSE)

Testing Checklist

  • Table loads with all columns
  • Search filters events correctly
  • Status filter works for all statuses
  • Event type filter works for all types
  • Sort by timestamp/event type/status works
  • Sort order toggle works
  • Retry button only shows for failed events
  • Retry triggers API call and updates UI
  • View button opens modal with full details
  • Modal displays formatted JSON
  • Copy to clipboard works
  • Modal closes on ESC key
  • Modal closes on backdrop click
  • Empty state displays when no results
  • Real-time updates work (if enabled)
  • Responsive on mobile devices
  • Keyboard navigation works
  • Screen reader announces status changes
  • Color contrast meets WCAG AA
  • No TypeScript errors
  • No console errors

Future Enhancements

  • Pagination for large datasets
  • Bulk retry for multiple failed events
  • Export events to CSV/JSON
  • Webhook endpoint management
  • Event replay functionality
  • Advanced filtering (date range, HTTP status)
  • Webhook delivery analytics dashboard
  • Custom retry strategies per event type
  • Webhook signature verification logs
  • Integration with monitoring tools (Sentry, DataDog)

Performance Considerations

  • Virtual scrolling for large event lists
  • Debounced search input
  • Memoized filter functions
  • Lazy loading of event details
  • Optimistic UI updates
  • Request caching with React Query
  • Server-side pagination
  • WebSocket for real-time updates (instead of polling)

Security Considerations

  • Admin-only access (add authentication middleware)
  • Rate limiting on retry endpoint
  • Payload sanitization in display
  • CSRF protection on POST endpoints
  • Audit logging for retry actions
  • Sensitive data masking in payloads
  • Role-based access control (RBAC)

Status: ✅ Implementation Complete Last Updated: February 24, 2026 Developer: Senior Developer Implementation