Base URL: https://api.orceum.com/v1 These endpoints are used by your app to push events to Orceum (not by users). Authentication uses your app’s whs_* webhook secret combined with HMAC signature.

​
Push an Event

POST /apps/{app_id}/events
Pushes a real-time event into the assistant’s conversation pipeline for a specific user’s installation.

​
Required Headers

HeaderValue
Content-Typeapplication/json
X-Orceum-Webhook-SecretYour whs_* secret
X-Hub-Signature-256sha256=<hmac_hex> — HMAC-SHA256 of the compact request body
X-TimestampISO 8601 UTC timestamp

​
Request Body

​
installation_id
string
required
The Orceum installation ID of the user to notify. From the INSTALLED lifecycle webhook.
​
event_type
string
required
A dot-separated event descriptor (e.g., task.completed, payment.failed, export.ready).Note: These event types are entirely custom and defined by you. Orceum does not enforce a predefined list of events. The Orceum AI simply reads this string to understand the context of what happened in your external system.
​
event_data
object
required
Payload with all relevant context. The assistant uses this to compose the message to the user. Be specific.
​
timestamp
string
required
ISO 8601 UTC timestamp of when the event occurred, e.g. 2024-01-15T12:00:00Z
​
priority
string
default:"normal"
Event urgency. Affects delivery behavior.
ValueBehavior
lowMay be batched into digest
normalStandard delivery
highPrioritized, less likely to be deferred
criticalImmediate delivery regardless of user settings
​
metadata
object
Optional key-value pairs for your tracking. Not shown to users.

​
Example Request

curl -X POST https://api.orceum.com/v1/apps/{app_id}/events \
  -H "Content-Type: application/json" \
  -H "X-Orceum-Webhook-Secret: whs_your_secret" \
  -H "X-Hub-Signature-256: sha256=abc123def456..." \
  -H "X-Timestamp: 2024-01-15T12:00:00Z" \
  -d '{
    "installation_id": "inst_abc123",
    "event_type": "task.completed",
    "event_data": {
      "task_id": "task_789",
      "title": "Send Q4 report",
      "completed_at": "2024-01-15T12:00:00Z"
    },
    "timestamp": "2024-01-15T12:00:00Z",
    "priority": "normal"
  }'

​
Response 200

{
  "event_id": "evt_abc123",
  "status": "QUEUED",
  "action_taken": "CONVERSATION_STARTED"
}
​
event_id
string
Unique ID for this event. Use for debugging and support.
​
status
string
Current event status: QUEUED, PROCESSING, PROCESSED, IGNORED, DEFERRED
​
action_taken
string
What Orceum did with the event:
ValueMeaning
NOTIFIEDPush notification sent, no new conversation
CONVERSATION_STARTEDNew conversation opened with event context
QUEUEDQueued for digest delivery
IGNOREDFiltered out (low priority, quiet hours, bouncer decision)

​
Error Responses

StatusCause
401Invalid or missing signature
404installation_id not found or not active
422Invalid request body (missing required fields)
429Rate limit exceeded

​
Verify Webhook Setup

You can verify that your webhook endpoint is configured and reachable directly from the Orceum Developer Studio. Navigate to your app’s Webhooks tab and click Test Webhook. Orceum will attempt to ping your endpoint and report if it is reachable and properly configured.