Docs / Workflows / Events
Events
Every change becomes an event. Events start work.
OAIZ turns changes in your systems into events and keeps them in order, newest on top. A new email, an updated contract, a deal that moves stage, or a reading from your own system each becomes one event.
A workflow starts when its trigger arrives: the event type a job listens for is that job’s trigger. A job can publish a new event back on the queue, and that event can start the next workflow.
What is in an event
Every event has two parts. The type says what happened, such as an email that arrived. The properties are the content of that change, as JSON. Each type has its own shape: an email has a sender and a subject, and a Linear issue has a title and a state.
- eventType
- A provider and a name. OAIZ writes it as e:provider/name, for example e:custom/customer-message. Jobs listen for a type.
- properties
- The content of the change, as JSON. A job reads one value by its path. On an email, properties.subject is the subject and properties.from.address is the sender.
- timestamp
- Optional. When the change happened. OAIZ uses the time it receives the event if you leave it out.
- uniqueKey
- Optional. OAIZ does not store a second event with the same type and key in your organization. Different event types can reuse the same key.
- hasFiles
- A boolean at the event root in API responses and workflow contexts. True means OAIZ has at least one stored file associated with the event. Attachment properties and dropped files alone give false. One stored file alongside dropped files gives true. OAIZ sets this value from stored file references.
- files
- Optional. References to files that belong to the change, such as a scanned page.
Example events
These are the shapes OAIZ stores for a few integration events. Open one to see its properties. The values are examples.
{
"from": {
"address": "customer@example.com",
"display_name": "Customer Example"
},
"subject": "Customer onboarding question",
"body": "<p>Example HTML body</p>",
"labels": ["INBOX", "UNREAD", "Customer"],
"attachments": [{ "filename": "requirements.pdf", "size": 24576 }],
"thread_id": "thread-example-001"
}{
"action": "create",
"entity_identifier": "ENG-123",
"entity_title": "Example issue",
"entity_state": { "name": "Todo" },
"entity_priority": 2,
"actor_name": "Example User"
}{
"channel": "C0123456789",
"channel_type": "channel",
"user": "U0123456789",
"text": "Example channel update for the project.",
"ts": "1715142000.000000"
}{
"file": {
"name": "Q4 budget.pdf",
"mimeType": "application/pdf"
},
"lastModifiedBy": {
"displayName": "Sam Rivera",
"email": "sam@example.com"
},
"changedAt": "2026-09-12T11:30:00.412Z"
}{
"objectSlug": "deals",
"attributeTitle": "Stage",
"currentStatusTitle": "In Progress",
"changed_fields": ["stage"]
}Where events come from
- Integrations
- Connected services, such as Gmail, Outlook, Linear, Slack, Google Drive, and Attio, publish their changes as events. You do not write any code for these.
- Your systems
- Internal tools, sensors, and scripts send events to the OAIZ API with an API key. The next section shows how.
- Workflows
- A job can publish an output event. It lands on top of the queue like any other event, so it can start the next job or another workflow.
Send an event
Post the event to the ingest API. Use the provider custom for events from your own systems. Every live workflow whose trigger is that type starts.
curl -X POST https://api.oaiz.io/ingest/event/publish \
-H "Authorization: Bearer $OAIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"eventType": { "provider": "custom", "name": "customer-message" },
"properties": {
"message": "Please change my billing address to 12 Example Street."
},
"uniqueKey": "ticket-1042"
}'



