​

Events API

• Envelope v1: response es { object: 'event', id, type, status, created_at }.
• Idempotencia por Idempotency-Key header — repeticiones devuelven mismo id con status: 'idempotent'.
• Validación Zod estricta por event_type. Tipos no registrados → 400 event_type_unknown.
• Rate limit 200 req/min por IP, exponiendo headers X-RateLimit-*.
• Logs estructurados y métricas PostHog.

Para consumir el catálogo de tipos en código, ver apps/backend/src/notifications/engine/schemas/event-schemas.ts (Zod schemas — fuente de verdad).

​

Request

POST /api/public/events/ingest
Content-Type: application/json
x-api-key: <NOTIFICATIONS_API_KEY>
Idempotency-Key: <string arbitrario, opcional, recomendado>

{
  "event_type": "booking.created",
  "aggregate_id": "booking_abc123",
  "aggregate_type": "booking",
  "source": "vivla-backend",
  "payload": { ... }
}

Nota v3.1: el body field event_id fue eliminado. La idempotencia se hace siempre vía header Idempotency-Key.

​

User identity

SELECT id, vivla_user_id FROM users WHERE id = <payload.userId>

• Si tu sistema ya tiene el Firebase UID, mapealo via SELECT id FROM users WHERE vivla_user_id = $1 antes de emitir.
• Lo ideal a mediano plazo es que vivla-backend reciba el UUID Supabase en su propio modelo (ya sea propagándolo desde vivla-tools al crear usuarios, o consultando vivla-tools en lookup).

Por qué importa: notifications.created_by, notifications.target_audience.user_ids, e inbox_messages.recipient_id son FKs/constraints a users.id. Un Firebase UID en esos campos rompe el insert silenciosamente. El push dispatch además consulta device_tokens en la PG de vivla-backend, indexada por vivla_user_id — el engine se encarga del mapping, los integradores solo envían users.id.

​

Headers

​

Response

​

Ejemplo: booking.created

curl -i -X POST 'https://tools.vivla.com/api/public/events/ingest' \
  -H 'x-api-key: <NOTIFICATIONS_API_KEY>' \
  -H 'Idempotency-Key: booking_abc123_created' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "booking.created",
    "aggregate_id": "booking_abc123",
    "aggregate_type": "booking",
    "source": "vivla-backend",
    "payload": {
      "bookingId": "booking_abc123",
      "ownerId": "user_xyz",
      "ownerName": "Juan Pérez",
      "ownerEmail": "juan@example.com",
      "propertyId": "prop_001",
      "propertyName": "Casa del Mar",
      "propertyLocation": "Ibiza",
      "startDate": "2026-06-15",
      "endDate": "2026-06-22"
    }
  }'

const res = await fetch('https://tools.vivla.com/api/public/events/ingest', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.NOTIFICATIONS_API_KEY!,
    'Idempotency-Key': `booking_${booking.id}_created`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_type: 'booking.created',
    aggregate_id: booking.id,
    aggregate_type: 'booking',
    source: 'vivla-backend',
    payload: {
      bookingId: booking.id,
      ownerId: booking.ownerId,
      ownerName: booking.ownerName,
      ownerEmail: booking.ownerEmail,
      propertyId: booking.propertyId,
      propertyName: booking.propertyName,
      propertyLocation: booking.propertyLocation,
      startDate: booking.startDate,
      endDate: booking.endDate,
    },
  }),
})
const event = await res.json()

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Request-ID: req_a1b2c3d4e5f6
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 60

{
  "object": "event",
  "id": "ev_550e8400-e29b-41d4-a716-446655440000",
  "type": "booking.created",
  "status": "pending",
  "created_at": "2026-05-05T10:00:00.000Z"
}

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: req_b2c3d4e5f6g7

{
  "object": "event",
  "id": "ev_550e8400-e29b-41d4-a716-446655440000",
  "type": "booking.created",
  "status": "idempotent",
  "created_at": "2026-05-05T10:00:00.000Z"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-ID: req_c3d4e5f6g7h8

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Payload does not match schema for booking.created",
    "param": "bookingId",
    "request_id": "req_c3d4e5f6g7h8",
    "details": [
      { "path": "bookingId", "message": "Required" }
    ]
  }
}

​

Catálogo de eventos

​

Onboarding

​

Reservas (vivla-backend)

​

Llaves (vivla-backend, incluye crons internos)

​

Encuestas (vivla-tools internal)

​

Oportunidades (Windmill cron)

​

Lifecycle de usuario (Windmill cron)

​

Eventos derivados (Windmill cron — reemplazan delays del builder)

​

Eventos descartados (no emitir)

​

Convenciones de naming

• *Date (ej. startDate, endDate, expiresAt): ISO 8601 — bien YYYY-MM-DD (date) o YYYY-MM-DDTHH:mm:ssZ (datetime). Los schemas aceptan ambos.
• *At (ej. expiresAt, previousExpiresAt): timestamp con time.
• Transiciones: el field sin prefijo es el valor actual / efectivo; previous* / new* / old* describe la transición.

​

Listar tipos vía API

GET /api/public/events/registered-events

→ {
  "object": "list",
  "data": ["user.welcomed", "booking.created", "booking.cancelled", ...]
}

​

Health check

GET /api/public/events/health

→ {
  "object": "health",
  "stuck_events": 0,
  "failed_events": 0
}

​

Errores comunes

• event_type_unknown → revisa la grafía exacta y la versión del catálogo. Lista actualizada vía GET /public/events/registered-events.
• validation_error con param: aggregate_id → falta el field en el payload, o tiene tipo incorrecto.
• 429 con Retry-After: 12 → has superado 200 req/min. Encadena retries con jitter.
• 401 authentication_invalid → confirma que estás enviando el header x-api-key (no Authorization: Bearer) y que el valor es el de la env actual (NOTIFICATIONS_API_KEY).

​

Referencias

• Convenciones API — envelope, request_id, headers cross-cutting.
• Códigos de error — catálogo completo.
• Idempotency — header Idempotency-Key.
• Automaciones — visión general del epic + builder.
• Backend handoff: docs/internal/tools/notifications/implementation/epics/notification-automation-system/specs/backend-handoff.md
• Catálogo en código (Zod schemas, fuente de verdad): apps/backend/src/notifications/engine/schemas/event-schemas.ts