Sign in

v1

latestOpenAPI 3.1.02026-07-2670105729.6 KB
Automations

Fire a trigger

Fires the trigger: validates payload against the trigger’s payloadSchema, upserts the contact derived from the payload, and starts one run per published automation attached to the trigger. Read details.automationRunIds[] and follow each via GET /v1/automations/runs?automationRunId=.

Idempotency — send a stable Idempotency-Key header on every retry (the body field idempotencyKey is a legacy alternative). Replays return the original run ids with status: "idempotent_replay" instead of starting duplicates.

Response-shape note — this endpoint responds with the legacy fire envelope { success, status, code, message, receivedAt, details } (shared with internal webhook infrastructure) rather than a bare resource. It is the ONE exception to the v1 response conventions; treat status + code as the discriminators.

post/v1/automations/triggers/{triggerEventId}/fire

Path parameters

triggerEventIdstring required

Trigger id returned by POST /v1/automations/triggers. Custom triggers use tri_… ids; integration triggers use composite ids (e.g. clerk:org_…:brand_…:user.created, URL-encode the colons).

Example:tri_signup

Trigger id returned by POST /v1/automations/triggers. Custom triggers use tri_… ids; integration triggers use composite ids (e.g. clerk:org_…:brand_…:user.created, URL-encode the colons).

Headers

Idempotency-Keystring

Optional idempotency key for safe retries. Reusing the same key with the same request body returns the original response for 24 hours.

Request body

payloadobject required

Event payload — fields and types must match the trigger's payloadSchema. Unknown fields are accepted but reported as unexpected_key warnings.

idempotencyKeystring

Legacy body-field alternative to the Idempotency-Key HTTP header. Prefer the header for new integrations. The token is namespaced server-side with the API key org so different tenants cannot collide.

Response

Fired (status: "triggered") or idempotent replay (status: "idempotent_replay"). details.automationRunIds[] carries one run id per matched published automation.

successboolean required
status'triggered' | 'idempotent_replay' | 'ready' | 'invalid_api_key' | 'invalid_json' | 'failed' | 'forbidden' | 'payload_mismatch' | 'trigger_event_not_found' required

Discriminator for the response category. Pairs with code. A trigger with no published automation attached returns status: "failed" + code: "NO_PUBLISHED_AUTOMATION" (HTTP 422). Successful fires always return status: "triggered".

codestring required
messagestring required
triggerEventIdstring
receivedAtstring required

ISO-8601 timestamp the request was processed at.