> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capedigital.co.ke/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest a notification event

> Creates one Notification per recipient and dispatches it to the resolved delivery channels (websocket, email, sms, push). Called by other backend services, not directly by frontends.



## OpenAPI

````yaml /openapi/shared.yaml post /api/v1/notifications/events
openapi: 3.0.3
info:
  title: Shared Service API
  version: 1.0.0
  description: |2-

        **Shared Service API** - Comprehensive shared service and management system.

        ## Versionings
        The API uses URL path versioning (e.g., `/api/v1/`, `/api/v2/`).
        Current version: **v1**
        
  contact:
    name: API Support
    email: thakacreations@gmail.com
  license:
    name: thakacreations
servers: []
security: []
paths:
  /api/v1/notifications/events:
    post:
      tags:
        - notifications
      summary: Ingest a notification event
      description: >-
        Creates one Notification per recipient and dispatches it to the resolved
        delivery channels (websocket, email, sms, push). Called by other backend
        services, not directly by frontends.
      operationId: notifications_events_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationEventRequest'
            examples:
              TaskAssignment(studio,Websocket+Email):
                value:
                  source_service: assignment-service
                  notification_type: task.assigned
                  actor_id: <uuid>
                  recipient_ids:
                    - <uuid>
                  title: New task assigned to you
                  body: STORY-123 has been assigned to you
                  data:
                    task_id: <uuid>
                    entity_reference: STORY-123
                  entity_type: task
                  entity_id: <uuid>
                  channels:
                    - websocket
                    - email
                  recipient_meta_map:
                    <uuid>:
                      email: user@example.com
                      phone: '+254700000000'
                summary: Task assignment (studio, websocket + email)
              EpisodePublished(Vibe47,Push):
                value:
                  source_service: digi-content
                  notification_type: episode.published
                  actor_id: <uuid>
                  recipient_ids:
                    - <uuid>
                  title: New episode of Nairobi Nights
                  body: S2E4
                  data:
                    show_id: <uuid>
                  entity_type: episode
                  entity_id: <uuid>
                  channels:
                    - push
                  recipient_meta_map: {}
                summary: Episode published (Vibe47, push)
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NotificationEventRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/NotificationEventRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationEventCreateResponse'
          description: ''
      security:
        - bearerAuth: []
components:
  schemas:
    NotificationEventRequest:
      type: object
      description: >-
        Inbound payload from other services posting a notification event.


        Example:
            {
                "source_service": "assignment-service",
                "notification_type": "task.assigned",
                "actor_id": "uuid",
                "recipient_ids": ["uuid-1"],
                "title": "New task assigned to you",
                "body": "STORY-123 has been assigned to you",
                "data": {"task_id": "uuid", "entity_reference": "STORY-123"},
                "entity_type": "task",
                "entity_id": "uuid",
                "channels": ["websocket", "email"],
                "recipient_meta_map": {
                    "uuid-1": {"email": "user@example.com", "phone": "+254700000000"}
                }
            }

        Example (Vibe47 content, push):
            {
                "source_service": "digi-content",
                "notification_type": "episode.published",
                "actor_id": "uuid",
                "recipient_ids": ["uuid-1"],
                "title": "New episode of Nairobi Nights",
                "body": "S2E4",
                "data": {"show_id": "uuid"},
                "entity_type": "episode",
                "entity_id": "uuid",
                "channels": ["push"]
            }

        For "push", entity_type/entity_id are mapped to content_ref/content_id
        in

        the FCM data payload (see
        notifications.services.channels.push.PushChannel)

        and delivered to the recipient's registered device tokens.
      properties:
        source_service:
          type: string
          minLength: 1
          maxLength: 64
        notification_type:
          type: string
          minLength: 1
          maxLength: 64
        actor_id:
          type: string
          format: uuid
          nullable: true
        recipient_ids:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
        title:
          type: string
          minLength: 1
          maxLength: 255
        body:
          type: string
          default: ''
        data:
          type: object
          additionalProperties: {}
        entity_type:
          type: string
          default: ''
          maxLength: 64
        entity_id:
          type: string
          format: uuid
          nullable: true
        channels:
          type: array
          items:
            enum:
              - websocket
              - email
              - sms
              - push
            type: string
            description: |-
              * `websocket` - websocket
              * `email` - email
              * `sms` - sms
              * `push` - push
            x-spec-enum-id: 6d9732a7dc7cd1ea
          nullable: true
        recipient_meta_map:
          type: object
          additionalProperties:
            type: object
            additionalProperties: {}
          description: >-
            Maps recipient_id (str) → {email, phone}. Required for email/SMS
            channel delivery.
      required:
        - notification_type
        - recipient_ids
        - source_service
        - title
    NotificationEventCreateResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          $ref: '#/components/schemas/NotificationEventCreateData'
      required:
        - data
        - message
        - success
    NotificationEventCreateData:
      type: object
      properties:
        created:
          type: integer
      required:
        - created
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your JWT token in the format: Bearer <token>'

````