Notifications

The notifications system is event-driven. Emitting an event causes the notification engine to evaluate registered rules and deliver notifications through the appropriate channels (in-app, email, WhatsApp).

Emit a notification event

POST /api/notifications/emit

string

Emits a named notification event with an optional context payload. The notification engine expands the event into one or more delivery effects based on registered rules.

Authentication

This endpoint accepts two modes:

Signed requests — the request body must be signed with the shared REQUEST_SIGNING_SECRET. The signature is verified before processing.
Unsigned requests — available when the REQUEST_SIGNING_DISABLED=1 environment variable is set (development/testing only).

Do not disable request signing in production. Unsigned requests bypass the signature verification that prevents unauthorized event injection.

Workflow mode

When Inngest workflows are enabled (WORKFLOWS_DISABLED is not 1, or WORKFLOWS_ENABLED=1), the event is queued for asynchronous processing and the endpoint returns immediately. Otherwise, effects are evaluated synchronously and in-app notifications are inserted directly.

Request body

type

string

required

The event type identifier. Must match a registered notification rule. Examples: obra.completed, flujo.action.triggered, pendiente.due.

ctx

object

Context object passed to the notification rules. Shape depends on the event type.

Show Common context fields

tenantId

string | null

UUID of the tenant. If absent from ctx but present in the signed request metadata, it is merged automatically.

actorId

string | null

UUID of the user who triggered the event.

recipientId

string | null

UUID of the intended recipient user.

Response — workflow mode

boolean

required

Always true.

workflow

string

required

Always "queued" in workflow mode.

Response — direct delivery mode

boolean

required

Always true.

delivered

boolean

required

Always true when effects were processed.

inserted

number

required

Number of notifications rows inserted.

Error responses

Status	Description
`400`	Validation error — `type` is missing or the body is malformed.
`401`	Request signature is invalid or missing.
`500`	Internal error during event processing.

Request
Response (workflow mode)
Response (direct mode)

curl -X POST 'https://<domain>/api/notifications/emit' \
  --header 'Content-Type: application/json' \
  --header 'x-signature: <hmac-signature>' \
  --data '{
    "type": "obra.completed",
    "ctx": {
      "tenantId": "tenant-uuid-...",
      "actorId": "user-uuid-...",
      "obra": {
        "id": "obra-uuid-...",
        "name": "Escuela N° 42",
        "percentage": 100
      }
    }
  }'

{
  "ok": true,
  "workflow": "queued"
}

{
  "ok": true,
  "delivered": true,
  "inserted": 2
}

Notification schema

Notifications are stored in the notifications table and governed by per-user Row Level Security — users can only read and modify their own notifications.

Column	Type	Description
`id`	`uuid`	Primary key.
`user_id`	`uuid`	Recipient user.
`tenant_id`	`uuid \| null`	Tenant scope.
`title`	`text`	Notification title.
`body`	`text \| null`	Notification body text.
`type`	`text`	Notification type (`info`, `warning`, `error`, etc.).
`action_url`	`text \| null`	Deep link for the notification action.
`data`	`jsonb`	Arbitrary metadata payload.
`read_at`	`timestamptz \| null`	Timestamp when the user read the notification; `null` if unread.
`created_at`	`timestamptz`	Creation timestamp.

API Endpoints

Emit a notification event

Authentication

Workflow mode

Request body

Response — workflow mode

Response — direct delivery mode

Error responses

Notification schema

Build docs developers (and LLMs) love

API Endpoints

​Emit a notification event

​Authentication

​Workflow mode

​Request body

​Response — workflow mode

​Response — direct delivery mode

​Error responses

​Notification schema

Build docs developers (and LLMs) love

Emit a notification event

Authentication

Workflow mode

Request body

Response — workflow mode

Response — direct delivery mode

Error responses

Notification schema