---
title: "Fire a trigger"
method: POST
path: "/v1/automations/triggers/{triggerEventId}/fire"
tags: ["Automations"]
---

# Fire a trigger

`POST /v1/automations/triggers/{triggerEventId}/fire`

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.

## Path parameters

- `triggerEventId` string, 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).

## Headers

- `Idempotency-Key` string

## Request body

- TriggerFireRequest
  - `payload` object, required — Event payload — fields and types must match the trigger's `payloadSchema`. Unknown fields are accepted but reported as `unexpected_key` warnings.
  - `idempotencyKey` string — 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 `200`

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

- TriggerFireResponse
  - `success` boolean, 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"`.
  - `code` string, required
  - `message` string, required
  - `triggerEventId` string
  - `receivedAt` string, required — ISO-8601 timestamp the request was processed at.
  - `details` object
    - `resolvedPayload` object
    - `warnings` unknown[]
      - unknown
    - `idempotencyKey` string
    - `triggerInstanceId` string — Unique identifier for the persisted inbound row. Useful for support and replay. Set whenever an Idempotency-Key was provided.
    - `publishedTransactionalEmails` object[]
      - `emailId` string, required
    - `publishedAutomations` object[]
      - `automationId` string, required
      - `title` string
    - `automationRunIds` string[]
    - `counts` object
      - `transactionalEmails` integer, required
      - `automations` integer, required

## Other responses

- `400` — Invalid JSON, or the payload does not satisfy the trigger’s `payloadSchema` (`status: "payload_mismatch"`). Errors use the same fire envelope with `success: false`.
- `401` — The API key was missing, invalid, or revoked.
- `403` — The caller does not have the required `automations` permission.
- `404` — The trigger does not exist in the API-key brand.
- `422` — No published automation is attached to the trigger.
- `429` — The request hit the rolling rate limit window.
- `500` — Unexpected internal error.

---

[API](https://skmtc.net/brew/apis/brew-public-api-v1.md) · [All operations](https://skmtc.net/brew/apis/brew-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brew/brew-public-api-v1/versions/db96cfedc6c5/schema)