Trigger a notification.
POST/v1/events/trigger
Accepts one event, resolves its priority, encodes it as Protobuf and
publishes it to NATS JetStream on the subject
notify.{class}.{channel}, where class is critical for
CRITICAL/HIGH (stream NOTIFY_CRITICAL) or bulk for NORMAL/LOW
(stream NOTIFY_BULK). The tenant is carried in the Protobuf payload, so
subject cardinality does not grow with signups and a bulk campaign can never
sit in front of another customer's OTP. The call returns as soon as the
broker acknowledges the write, so it is safe on a hot request path.
Idempotency. Send an Idempotency-Key header and a replay within the
retention window returns the original 200 response body instead of
enqueuing a second notification. Without the header, every call enqueues.
Rate limiting. Limits are applied per to.subscriberId, not per API
key, so one noisy end user cannot starve the rest of your traffic.
Request
Responses
- 200
- 202
- 400
- 401
- 429
- 500
- 503
Idempotent replay — the original response, replayed verbatim
Response Headers
IETF draft-11 remaining budget and reset for each ingest policy. Advisory only.
IETF draft-11 policy for each ingest tier (workspace, subscriber, monthly quota).
Event accepted and queued for delivery
Response Headers
IETF draft-11 remaining budget and reset for each ingest policy. Advisory only.
IETF draft-11 policy for each ingest tier (workspace, subscriber, monthly quota).
The recipient has no contact details for any channel
Missing or invalid API key
Rate limit exceeded (workspace RPS, per-subscriber abuse cap or monthly quota). The body's purpose names which limit was hit.
Response Headers
IETF draft-11 remaining budget and reset for each ingest policy. Advisory only.
IETF draft-11 policy for each ingest tier (workspace, subscriber, monthly quota).
Seconds to wait before retrying. Mandatory on every 429.
Encoding or broker failure
Rate-limit store unavailable (fail-closed) or broker unavailable. error is RATE_LIMIT_STORE_UNAVAILABLE for a store fault; the body carries no purpose.
Response Headers
Seconds to wait before retrying. Mandatory on every 503.