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. One of `userId` or `merchantId` is required
`merchantId`	string	Conditional	Identifier of the merchant the event concerns. One of `userId` or `merchantId` is required
`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

There is no timestamp field. Orca stamps the event on receipt.

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. Send userId, merchantId, or both — a request with neither is rejected with a VALIDATION_ERROR and nothing is stored. 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",
  "method": "mobile",
  "source": "ios-app",
  "reference": "session_9f2c1a",
  "metadata": {
    "ipAddress": "102.65.14.9",
    "attempts": 3,
    "mfaUsed": false
  }
}

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 neither userId nor merchantId. 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
}