VocalDocscontracts 1.65.0

Deliver a customer event to a Process

POST /v1/process-events

PropertyValue
Operationdeliver_process_event
GroupProcesses
Scopeevents:write
Route classcontrol
IdempotencyIdempotency-Key required: a retry with the same key replays the first answer
AuditAudited event.emitted (mutation)
Released in1.62.0
Phase 0 hostServed (the hosted api pins 1.65.0)

The alias of POST /v1/events by Process and correlation key (1.62.0; workflows-and-processes.md section 9.6): the same request with the Process target required, under events:write and an Idempotency-Key, recorded and answered as create_event records and answers it.

Request

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

curl -X POST "$VOCAL_API/v1/process-events" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom.payment.received",
    "process": {
      "process_id": "prc_..."
    }
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringyesA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: ProcessEventDeliveryRequest.

FieldTypeRequiredDescription
call_idCallIdnoA Call of the key's environment, live or ended within 24 hours (a target), which records custom.received.
datamap of anynoA JSON object of at most 32 KiB (a target) as canonical JSON, stored as a content pair. Content.
processCustomEventProcessTargetInputyes
typeCustomEventTypeyes

Responses

StatusContent typeShapeError codes
202application/jsonCustomEvent
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeprocess_not_active, idempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 202 answer

The shape is CustomEvent.

FieldTypeRequiredDescription
call_idCallId or nullyes
created_atTimestampyes
idEventIdyesThe id the event carries on every surface, assigned once in the request transaction: de-duplicate on it.
livemodebooleanyesTrue for the live environment.
object"custom_event"yes
process_event_idProcessEventId or nullyesThe Process event recorded for the Process target; null without one.
process_idProcessInstanceId or nullyesThe instance the request named by id; null for a correlation key or none.
typeCustomEventTypeyes
workflow_idWorkflowId or nullyes