API reference

Events

/events

Posting an event is what makes Raven send. Types come from the Subscription business pack and from your instance; GET /event-types is the truth for your instance.

GET/event-typesList types · pack plus instance GET/event-types/{type_key}Read a type · with payload schema POST/eventsRecord and judgeshown →GET/eventsList · ?q ?subject_id ?subject_ref ?type_key ?voided GET/events/{event_id}Read POST/events/{event_id}/voidVoid · calls off sends not yet gone

POSTRecord an event

Requires events:write. Records the event and judges it: every rule that names the type answers in the same transaction. Send Idempotency-Key or event_ref so a retry records once.

type_key Varies by pack

incident invoice_issued maintenance payment_failed payment_received plan_changed product_notice reminder renewal_due subscription_cancelled subscription_started trial_started usage_threshold

Incidentincidentscope: tenant

subject_id: Forbidden
group_id: Forbidden
date_field: —
dedupe_fields: ref, status

Body parameters

type_keystring · required

One of the types above.

subject_iduuid · forbidden

Raven's id for the subscription. Decided by the type's scope (tenant).

subject_refstring · forbidden · max 200

The same subscription, named by the reference you gave it: your own system knows SUB-2026-001, not Raven's id, so this saves it a lookup per event. Exactly one of the two.

group_iduuid · forbidden

occurred_atdatetime · optional

When it happened. Left out, now.

event_refstring · optional · max 200

Your own reference for this call; says what Idempotency-Key says.

payload

reftext · required

titletext · required

detailtext · optional

statustext · required

status_urltext · optional

Returns

201 with the event as stored, one fire per rule judged, and sends: how many messages that made. A type nobody defined is a 400 that lists the ones that are; a broken scope rule or payload is a 400 that names the field. Naming the subscription both ways is a 400, “Name the subject by subject_id or by subject_ref, not both.”, and a subject_ref nothing here holds is a 404. Everything after the reference is resolved is the same either way — the dedupe, the Idempotency-Key, the verdicts — and the event that comes back carries subject_id, so the answer tells you Raven's id.

Response body

One object: the same fields in every pack. Press Response on the sample to see one whole.

FieldTypeDescription

eventEventThe event as stored. Its fields are listed under it.

firesRuleFire[]One per rule that was judged against the event, whatever the verdict.

sendsintegerHow many sends that made: now, scheduled, or later in the send window.

batch_keystring | nullTies those sends together. null when there were none.

judgedintegerAlways 0 here; counts judgements on an internal replay.

Event event

FieldTypeDescription

iduuid

tenant_iduuidThe instance.

type_keystring

subject_iduuid | nullSet when the type's scope is subject — Raven's id, whether the call named the subscription by subject_id or by subject_ref.

group_iduuid | nullSet when the type's scope is group.

occurred_atdatetimeAs sent, or when it was recorded.

effective_datedate | nullThe value of the type's date_field: what a rule in days counts from.

effective_atdatetime | nullThe same, where the date field is a date and time: what a rule in minutes counts from.

payloadobjectAs checked against the type's payload_schema.Varies by pack

dedupe_keystringMade from the type's dedupe_fields. The same key is the same event.

sourceapi | upload | manualapi for anything recorded with a key.

upload_iduuid | null

created_byuuid | nullThe key's id, for an event recorded through the API.

created_by_namestring | null“API key · ” and the key's name.

voided_atdatetime | nullSet once the event has been taken back.

voided_byuuid | null

void_reasonstring | null

voided_by_event_iduuid | nullSet when another event cleared this one, rather than a person or a key voiding it.

created_atdatetime

updated_atdatetime

Rule fire fires[]

FieldTypeDescription

iduuid

tenant_iduuid

rule_iduuid

event_iduuid | null

send_iduuid | nullThe send this verdict made, if it made one.

nudge_iduuid | null

outcomestringsent · scheduled · nudged · dry_run · not_matched · no_audience · no_wording · window_closed · already_fired · voided.

detailobjectWhy, in the rule's own terms.

fired_atdatetime

On failure the body is { error, code } instead.

Previous← Authentication, keys and scopes NextEvent types →