Deliver an event to a Process instance

POST /v1/processes/{process_id}/events

Property	Value
Operation	`create_process_event`
Group	Processes
Scope	`processes:write`
Route class	`control`
Idempotency	`Idempotency-Key` required: a retry with the same key replays the first answer
Audit	Audited `processes.event.deliver` (mutation)
Released in	1.62.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Records a Process event for one instance, source customer, and writes its event command, and answers 202 with the event matched (1.62.0); an instance not yet waiting for it gets it once it waits. A name the platform delivers is event_name_reserved and data above 32 KiB (a target) data_too_large (ProcessEventIssueCode); an instance that ended is process_not_active. The Idempotency-Key records a repeated delivery once.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the processes:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/processes/prc_.../events" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "<name>" }'

const response = await fetch(`${process.env.VOCAL_API}/v1/processes/prc_.../events`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<name>"
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/processes/prc_.../events",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "<name>",
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`process_id`	path	ProcessInstanceId	yes	The id of a Process instance: `prc_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`idempotency-key`	header	string	yes	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: ProcessEventCreateRequest.

Field	Type	Required	Description
`data`	map of any	no	A JSON object of at most 32 KiB (a target). Content.
`name`	WorkflowName	yes	The name a `wait` node of the instance lists.

Responses

Status	Content type	Shape	Error codes
`202`	`application/json`	ProcessEvent
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`process_not_active`, `idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `202` answer

The shape is ProcessEvent.

Field	Type	Required	Description
`created_at`	Timestamp	yes
`custom_event_id`	EventId or null	yes	The customer-emitted event it came from, through POST `/v1/events`; null otherwise.
`data`	object or null	yes	Content; null unless the read names `include=content`, and on every write.
`id`	ProcessEventId	yes
`name`	WorkflowName	yes	The name a `wait` node lists, such as `payment.received`.
`object`	`"process_event"`	yes
`process_ids`	array of ProcessInstanceId	yes	The instances it matched; empty when none.
`source`	ProcessEventSource	yes
`status`	ProcessEventStatus	yes
`workflow_id`	WorkflowId or null	yes	The Process it was delivered to; null for one delivered to an instance by id.