Event Endpoints

Submit non-monetary events — onboarding steps, banking-detail changes, terminal activations, settlement-configuration changes, support contacts — for ingestion and, where enabled, risk screening.

Events let rules react to behaviour that has no transaction attached. A merchant changing its settlement account shortly after a spike in refunds 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 `onboarding_submitted`, `bank_details_changed`, `terminal_activated`, `settlement_updated`. Must be non-empty
`merchantId`	string	Conditional	Identifier of the merchant the event concerns. One of `merchantId` or `userId` is required
`userId`	string	Conditional	Identifier of the user the event concerns. One of `merchantId` or `userId` 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 merchantId, userId, or both — a request with neither is rejected with a VALIDATION_ERROR and nothing is stored. For B2B integrations merchantId is the normal key; userId is available where the event concerns an individual, such as a merchant’s authorised operator.

Example Request


{
  "id": "EVT123456",
  "type": "bank_details_changed",
  "merchantId": "MERCH123456",
  "method": "web",
  "source": "merchant-portal",
  "reference": "change_req_9f2c1a",
  "metadata": {
    "previousBankName": "Test Bank",
    "newBankName": "Example Bank",
    "changedBy": "merchant_admin"
  }
}

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": "REVIEW",
  "triggered": [
    {
      "id": "TRIG123456",
      "name": "Settlement account changed after refund spike",
      "level": "high",
      "reason": "Merchant changed banking details within 7 days of an elevated refund rate",
      "recommendedAction": "REVIEW"
    }
  ],
  "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 merchantId nor userId. 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
}