Event Endpoints

Submit non-monetary events — logins, profile changes, password resets, KYC submissions, support contacts — for ingestion and, where enabled, risk screening.

Events let rules react to behaviour that has no transaction attached. A burst of failed logins followed by a bank-detail change is invisible to transaction monitoring, but visible here.

Not to be confused with webhook event types. This endpoint is how you send events into Orca. The event field values in Webhooks are outbound notifications Orca sends to you. The two vocabularies are unrelated: type here is free-form and defined by you.

Submit Event

Endpoint


POST /v1/event

Request Schema

Field	Type	Required	Description
`id`	string	Yes	Your unique identifier for this event. Must be non-empty
`type`	string	Yes	Event type. Free-form and defined by you, for example `login`, `password_reset`, `profile_update`, `kyc_submitted`. Must be non-empty
`userId`	string	Conditional	Identifier of the user the event concerns. Provide `userId` or `user`, not both
`user`	object	Conditional	A full user object to create or update the user inline, as an alternative to `userId`. See User for the object shape
`merchantId`	string	Conditional	Identifier of the merchant the event concerns. Provide `merchantId` or `merchant`, not both
`merchant`	object	Conditional	A full merchant object to create or update the merchant inline, as an alternative to `merchantId`
`timestamp`	number	No	When the event happened, in Unix epoch milliseconds. Defaults to the time of the request
`reference`	string	No	Your own reference for the event, if it relates to something trackable in your system. Must be non-empty if sent
`method`	string	No	How the event occurred, for example `web`, `mobile`, `ussd`, `api`. Must be non-empty if sent
`source`	string	No	Where the event originated, for example a service or channel name. Must be non-empty if sent
`metadata`	object	No	Free-form key/value object for anything else you want available to rules
`paymentInstrumentId`	string	No	Identifier of a payment instrument, such as a bank account, the event concerns. Must be non-empty if sent
`groupingId`	string	No	Identifier that groups related events together, so a series of events about the same subject or case can be correlated. Must be non-empty if sent

Timestamps

timestamp is when the event occurred, not when you sent it. Omit it for live traffic. Send it whenever the event is not being reported live, i.e. on any backfill or replay.

Note: type and method are lowercased when stored, so LOGIN and login are the same event type. Rules and event-window aggregations match on the lowercased value.

Subject is required

An event must be about someone. Provide a subject as an id (userId or merchantId) or as an inline object (user or merchant) — at least one is required, and a request with none is rejected with a VALIDATION_ERROR and nothing is stored. For a given subject, send the id or the object, not both: userId with user, or merchantId with merchant, is rejected. An inline user or merchant object is created or updated as part of the request. For B2C integrations userId is the normal key; merchantId is available if the event concerns a merchant counterparty.

Example Request


{
  "id": "EVT123456",
  "type": "login",
  "userId": "USER123",
  "timestamp": 1734167723000,
  "method": "mobile",
  "source": "ios-app",
  "reference": "session_9f2c1a",
  "metadata": {
    "ipAddress": "102.65.14.9",
    "attempts": 3,
    "mfaUsed": false
  }
}

To create or update the subject inline, send a user object instead of userId (see User for the full shape). This example also carries paymentInstrumentId and groupingId to tie the event to an account and a related series of events:


{
  "id": "EVT123457",
  "type": "bank_account_added",
  "user": {
    "id": "USER123",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "paymentInstrumentId": "PINST987654",
  "groupingId": "USER123",
  "timestamp": 1734167723000,
  "method": "web",
  "source": "web-app"
}

Response

The response depends on whether event rules are enabled for your client.

With event rules enabled

You receive a risk assessment synchronously, and an event.screened webhook is delivered.

Field	Type	Description
`id`	string	The event identifier you submitted
`riskLevel`	enum	Risk assessment: `low`, `medium_low`, `medium`, `high`, `very_high`, `n/a`
`recommendedAction`	enum	Suggested action: `ALLOW`, `REVIEW`, `BLOCK`, `STEP_UP_AUTH`, `STEP_UP_KYC`, `STEP_UP_ID`, `FLAG_FOR_MONITORING`, `REPORT_SUSPICIOUS`, `MESSAGE_USER`, `MESSAGE_MERCHANT`
`triggered`	array	Rules that triggered, empty if none
`timestamp`	number	Unix epoch milliseconds


{
  "id": "EVT123456",
  "riskLevel": "high",
  "recommendedAction": "STEP_UP_AUTH",
  "triggered": [
    {
      "id": "TRIG123456",
      "name": "Repeated failed logins from new IP",
      "level": "high",
      "reason": "Three failed login attempts from an unrecognised IP address",
      "recommendedAction": "STEP_UP_AUTH"
    }
  ],
  "timestamp": 1734167723000
}

With event rules disabled

The event is stored and acknowledged, with no assessment.


{
  "id": "EVT123456",
  "status": "success"
}

Note: Event rules are enabled per client. Contact support@orca-fraud.com to turn on event screening and receive risk assessments from this endpoint.

Responses

200: Event ingested, and screened if event rules are enabled
400: Validation failed, including a request with no subject (none of userId, user, merchantId, merchant), a subject sent as both an id and an object, or a timestamp that is not an integer, is in the future, or is more than a year old. See Error Reference
401: Unauthorized
500: Internal server error

Example Validation Error


{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      "/: Expected union value"
    ]
  },
  "timestamp": 1734167723000
}