Webhooks

{
  "id": "event-uuid",
  "topic": "cari.auth.user_created",
  "timestamp": "2026-04-18T10:30:00Z",
  "payload": {
    "user_id": "user-uuid",
    "email": "newuser@example.com",
    "registration_role": "DOCTOR"
  }
}

POST /api/webhooks/stripe

// Stripe sends events for:
// - checkout.session.completed
// - invoice.payment_succeeded
// - invoice.payment_failed
// - customer.subscription.updated
// - customer.subscription.deleted

// The webhook handler verifies the Stripe signature header
// and processes subscription/payment state changes.

POST /api/webhooks/livekit

// LiveKit sends events for telemedicine sessions:
// - room_started — A video room was created
// - room_finished — A video room ended
// - participant_joined — A participant entered the room
// - participant_left — A participant left the room
// - track_published — A media track was published

// Signature verification is performed inside the handler.

// Orange Money payment callbacks
POST /api/payments/webhooks/orange-money

// MTN MoMo payment callbacks
POST /api/payments/webhooks/mtn-momo

// These endpoints receive payment status updates:
// - Payment successful
// - Payment failed
// - Payment pending/timeout

// WhatsApp Business API webhook verification
GET /webhook

// WhatsApp incoming message handler
POST /webhook

// Handles:
// - Incoming patient messages
// - Delivery receipts
// - Read receipts

// Resend email delivery events
POST /api/gtm/webhooks/resend

// Inbound lead capture from external forms
POST /api/gtm/webhooks/inbound

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "cari.auth.user_created",
  "timestamp": "2026-04-18T10:30:00Z",
  "source_service": "cari-auth",
  "payload": {
    // Topic-specific payload
  }
}

// Example: User Created Event
{
  "id": "event-uuid",
  "topic": "cari.auth.user_created",
  "timestamp": "2026-04-18T10:30:00Z",
  "payload": {
    "user_id": "user-uuid",
    "email": "doctor@hospital.org",
    "first_name": "Sarah",
    "last_name": "Chen",
    "registration_role": "DOCTOR"
  }
}

// Example: Organization Member Added
{
  "id": "event-uuid",
  "topic": "cari.organization.member_added",
  "timestamp": "2026-04-18T11:00:00Z",
  "payload": {
    "organization_id": "org-uuid",
    "user_id": "user-uuid",
    "role": "ORG:DOCTOR"
  }
}

// List all failed events
GET /admin/dlq

// Check DLQ depth and alert status
GET /admin/dlq/depth

// Response:
{
  "depth": 3,
  "alert": true,
  "oldest_event": "2026-04-17T08:15:00Z"
}

// Retry a failed event (re-queues for processing)
POST /admin/dlq/:id/retry

// Discard a failed event permanently
DELETE /admin/dlq/:id

{
  "id": "dlq-entry-uuid",
  "event_id": "original-event-uuid",
  "topic": "cari.auth.user_created",
  "original_payload": "{ ... raw JSON ... }",
  "error": "Failed to parse envelope: missing field 'email'",
  "created_at": "2026-04-17T08:15:00Z"
}