# Shipfox events (https://www.shipfox.io/docs/integrations/shipfox/events)

Description: See which Shipfox run events can start a workflow and what each event contains.

> **Filter out your own runs (warn)**
> Shipfox doesn't stop a workflow from triggering itself. Filter on
> `event.project.name` and `event.run.origin`, and exclude the workflow's own
> path. See [Avoid trigger
> loops](https://www.shipfox.io/docs/how-to/author-workflows/run-after-another-workflow#avoid-trigger-loops).

Reruns and dev runs send these events too. Filter on `event.run.attempt == 1`
to skip reruns, or on `event.run.origin == 'synced'` to skip dev runs.

**Settings → Events** lists a Shipfox event only when a workflow was listening
for it. Runs that ended before you added the trigger have no event to inspect or
replay.

## Event catalog [#event-catalog]

The `shipfox` integration is available without any setup.

### Run requested

A workflow run attempt was requested.

**Payload:** Fields listed below.

| Field | Type | Required | Description |
|---|---|---|---|
| `project` | object | Required | Project that owns the run. |
| `project.id` | string (uuid) | Required |  |
| `project.name` | string | Required | Project name when Shipfox delivers the event. |
| `workflow` | object | Required | Workflow that the run executes. |
| `workflow.id` | string (uuid) | Required | Workflow definition ID. |
| `workflow.name` | string | Required |  |
| `workflow.path` | string \| null | Required | Workflow file path in the repository, for example `.shipfox/workflows/build.yml`. |
| `run` | object | Required | Run that the event is about. |
| `run.id` | string (uuid) | Required |  |
| `run.number` | integer | Required | Run number within the workflow. |
| `run.attempt` | integer | Required | Run attempt. A rerun increments it. |
| `run.name` | string | Required |  |
| `run.origin` | string: `synced`, `dev` | Required | `synced` for a run of a synced workflow definition, `dev` for a dev run. |
| `run.trigger` | object | Required | Trigger that started the run. |
| `run.trigger.source` | string | Required | Trigger `source` that started the run. |
| `run.trigger.event` | string | Required | Event name that started the run. |
| `run.ref` | string \| null | Required | Git ref of the run, when known. |
| `run.commit` | string \| null | Required | Git commit SHA of the run, when known. |
| `run.parent_run_id` | string (uuid) \| null | Required | ID of the run that started this run with `start_workflow_run`. |
| `run.root_run_id` | string (uuid) \| null | Required | ID of the first run in a chain of runs started with `start_workflow_run`. |
| `run.created_at` | string (date-time) | Required | Time the run was created. |
| `run.status` | string: `pending`, `waiting` | Required | `waiting` when the run waits for its concurrency group, otherwise `pending`. |

#### `run.requested`

A workflow run attempt was requested.

```yaml
triggers:
  on_run_requested:
    source: shipfox
    event: run.requested
```

### Run started

A workflow run attempt started running.

**Payload:** Fields listed below.

| Field | Type | Required | Description |
|---|---|---|---|
| `project` | object | Required | Project that owns the run. |
| `project.id` | string (uuid) | Required |  |
| `project.name` | string | Required | Project name when Shipfox delivers the event. |
| `workflow` | object | Required | Workflow that the run executes. |
| `workflow.id` | string (uuid) | Required | Workflow definition ID. |
| `workflow.name` | string | Required |  |
| `workflow.path` | string \| null | Required | Workflow file path in the repository, for example `.shipfox/workflows/build.yml`. |
| `run` | object | Required | Run that the event is about. |
| `run.id` | string (uuid) | Required |  |
| `run.number` | integer | Required | Run number within the workflow. |
| `run.attempt` | integer | Required | Run attempt. A rerun increments it. |
| `run.name` | string | Required |  |
| `run.origin` | string: `synced`, `dev` | Required | `synced` for a run of a synced workflow definition, `dev` for a dev run. |
| `run.trigger` | object | Required | Trigger that started the run. |
| `run.trigger.source` | string | Required | Trigger `source` that started the run. |
| `run.trigger.event` | string | Required | Event name that started the run. |
| `run.ref` | string \| null | Required | Git ref of the run, when known. |
| `run.commit` | string \| null | Required | Git commit SHA of the run, when known. |
| `run.parent_run_id` | string (uuid) \| null | Required | ID of the run that started this run with `start_workflow_run`. |
| `run.root_run_id` | string (uuid) \| null | Required | ID of the first run in a chain of runs started with `start_workflow_run`. |
| `run.created_at` | string (date-time) | Required | Time the run was created. |
| `run.status` | constant `"running"` | Required |  |
| `run.started_at` | string (date-time) | Required | Time the run attempt started running. |

#### `run.started`

A workflow run attempt started running.

```yaml
triggers:
  on_run_started:
    source: shipfox
    event: run.started
```

### Run completed

A workflow run attempt completed.

**Payload:** Fields listed below.

| Field | Type | Required | Description |
|---|---|---|---|
| `project` | object | Required | Project that owns the run. |
| `project.id` | string (uuid) | Required |  |
| `project.name` | string | Required | Project name when Shipfox delivers the event. |
| `workflow` | object | Required | Workflow that the run executes. |
| `workflow.id` | string (uuid) | Required | Workflow definition ID. |
| `workflow.name` | string | Required |  |
| `workflow.path` | string \| null | Required | Workflow file path in the repository, for example `.shipfox/workflows/build.yml`. |
| `run` | object | Required | Run that the event is about. |
| `run.id` | string (uuid) | Required |  |
| `run.number` | integer | Required | Run number within the workflow. |
| `run.attempt` | integer | Required | Run attempt. A rerun increments it. |
| `run.name` | string | Required |  |
| `run.origin` | string: `synced`, `dev` | Required | `synced` for a run of a synced workflow definition, `dev` for a dev run. |
| `run.trigger` | object | Required | Trigger that started the run. |
| `run.trigger.source` | string | Required | Trigger `source` that started the run. |
| `run.trigger.event` | string | Required | Event name that started the run. |
| `run.ref` | string \| null | Required | Git ref of the run, when known. |
| `run.commit` | string \| null | Required | Git commit SHA of the run, when known. |
| `run.parent_run_id` | string (uuid) \| null | Required | ID of the run that started this run with `start_workflow_run`. |
| `run.root_run_id` | string (uuid) \| null | Required | ID of the first run in a chain of runs started with `start_workflow_run`. |
| `run.created_at` | string (date-time) | Required | Time the run was created. |
| `run.status` | string: `succeeded`, `failed`, `cancelled` | Required | Final status of the run attempt. |
| `run.status_reason` | string \| null: `job_failed`, `timed_out`, `user_cancelled`, `concurrency_superseded`, `output_invalid`, `output_too_large` | Required | Why the run attempt failed or was cancelled, when known. |
| `run.started_at` | string (date-time) \| null | Required | Time the run attempt started running. `null` when it never started. |
| `run.finished_at` | string (date-time) | Required | Time the run attempt finished. |
| `run.outputs` | object \| null | Required | Workflow `outputs` of a succeeded run. `null` for other statuses. |

#### `run.completed`

A workflow run attempt completed.

```yaml
triggers:
  on_run_completed:
    source: shipfox
    event: run.completed
```

### Job queued

A job execution was queued for a runner.

**Payload:** Fields listed below.

| Field | Type | Required | Description |
|---|---|---|---|
| `project` | object | Required | Project that owns the run. |
| `project.id` | string (uuid) | Required |  |
| `project.name` | string | Required | Project name when Shipfox delivers the event. |
| `workflow` | object | Required | Workflow that the run executes. |
| `workflow.id` | string (uuid) | Required | Workflow definition ID. |
| `workflow.name` | string | Required |  |
| `workflow.path` | string \| null | Required | Workflow file path in the repository, for example `.shipfox/workflows/build.yml`. |
| `run` | object | Required | Run that the event is about. |
| `run.id` | string (uuid) | Required |  |
| `run.number` | integer | Required | Run number within the workflow. |
| `run.attempt` | integer | Required | Run attempt. A rerun increments it. |
| `run.name` | string | Required |  |
| `run.origin` | string: `synced`, `dev` | Required | `synced` for a run of a synced workflow definition, `dev` for a dev run. |
| `run.trigger` | object | Required | Trigger that started the run. |
| `run.trigger.source` | string | Required | Trigger `source` that started the run. |
| `run.trigger.event` | string | Required | Event name that started the run. |
| `run.ref` | string \| null | Required | Git ref of the run, when known. |
| `run.commit` | string \| null | Required | Git commit SHA of the run, when known. |
| `run.parent_run_id` | string (uuid) \| null | Required | ID of the run that started this run with `start_workflow_run`. |
| `run.root_run_id` | string (uuid) \| null | Required | ID of the first run in a chain of runs started with `start_workflow_run`. |
| `run.created_at` | string (date-time) | Required | Time the run was created. |
| `job` | object | Required | Job that the event is about. |
| `job.id` | string (uuid) | Required |  |
| `job.key` | string | Required | Job key in the workflow `jobs` map. |
| `job.mode` | string: `one_shot`, `listening` | Required | `listening` for a listening job, otherwise `one_shot`. |
| `job.execution` | object | Required | Job execution the event is about. |
| `job.execution.id` | string (uuid) | Required |  |
| `job.execution.sequence` | integer | Required | Execution number within the job. A listening job has one per event batch. |
| `job.status` | constant `"pending"` | Required |  |
| `job.queued_at` | string (date-time) | Required | Time the execution was queued. |

#### `job.queued`

A job execution was queued for a runner.

```yaml
triggers:
  on_job_queued:
    source: shipfox
    event: job.queued
```

### Job started

A runner claimed a job execution.

**Payload:** Fields listed below.

| Field | Type | Required | Description |
|---|---|---|---|
| `project` | object | Required | Project that owns the run. |
| `project.id` | string (uuid) | Required |  |
| `project.name` | string | Required | Project name when Shipfox delivers the event. |
| `workflow` | object | Required | Workflow that the run executes. |
| `workflow.id` | string (uuid) | Required | Workflow definition ID. |
| `workflow.name` | string | Required |  |
| `workflow.path` | string \| null | Required | Workflow file path in the repository, for example `.shipfox/workflows/build.yml`. |
| `run` | object | Required | Run that the event is about. |
| `run.id` | string (uuid) | Required |  |
| `run.number` | integer | Required | Run number within the workflow. |
| `run.attempt` | integer | Required | Run attempt. A rerun increments it. |
| `run.name` | string | Required |  |
| `run.origin` | string: `synced`, `dev` | Required | `synced` for a run of a synced workflow definition, `dev` for a dev run. |
| `run.trigger` | object | Required | Trigger that started the run. |
| `run.trigger.source` | string | Required | Trigger `source` that started the run. |
| `run.trigger.event` | string | Required | Event name that started the run. |
| `run.ref` | string \| null | Required | Git ref of the run, when known. |
| `run.commit` | string \| null | Required | Git commit SHA of the run, when known. |
| `run.parent_run_id` | string (uuid) \| null | Required | ID of the run that started this run with `start_workflow_run`. |
| `run.root_run_id` | string (uuid) \| null | Required | ID of the first run in a chain of runs started with `start_workflow_run`. |
| `run.created_at` | string (date-time) | Required | Time the run was created. |
| `job` | object | Required | Job that the event is about. |
| `job.id` | string (uuid) | Required |  |
| `job.key` | string | Required | Job key in the workflow `jobs` map. |
| `job.mode` | string: `one_shot`, `listening` | Required | `listening` for a listening job, otherwise `one_shot`. |
| `job.execution` | object | Required | Job execution the event is about. |
| `job.execution.id` | string (uuid) | Required |  |
| `job.execution.sequence` | integer | Required | Execution number within the job. A listening job has one per event batch. |
| `job.status` | constant `"running"` | Required |  |
| `job.runner_labels` | array of string \| null | Required | Labels of the runner that claimed the execution, when known. Minimum 1 item. |
| `job.started_at` | string (date-time) | Required | Time a runner claimed the execution. |

#### `job.started`

A runner claimed a job execution.

```yaml
triggers:
  on_job_started:
    source: shipfox
    event: job.started
```

### Job completed

A job completed or was skipped.

**Payload:** Fields listed below.

| Field | Type | Required | Description |
|---|---|---|---|
| `project` | object | Required | Project that owns the run. |
| `project.id` | string (uuid) | Required |  |
| `project.name` | string | Required | Project name when Shipfox delivers the event. |
| `workflow` | object | Required | Workflow that the run executes. |
| `workflow.id` | string (uuid) | Required | Workflow definition ID. |
| `workflow.name` | string | Required |  |
| `workflow.path` | string \| null | Required | Workflow file path in the repository, for example `.shipfox/workflows/build.yml`. |
| `run` | object | Required | Run that the event is about. |
| `run.id` | string (uuid) | Required |  |
| `run.number` | integer | Required | Run number within the workflow. |
| `run.attempt` | integer | Required | Run attempt. A rerun increments it. |
| `run.name` | string | Required |  |
| `run.origin` | string: `synced`, `dev` | Required | `synced` for a run of a synced workflow definition, `dev` for a dev run. |
| `run.trigger` | object | Required | Trigger that started the run. |
| `run.trigger.source` | string | Required | Trigger `source` that started the run. |
| `run.trigger.event` | string | Required | Event name that started the run. |
| `run.ref` | string \| null | Required | Git ref of the run, when known. |
| `run.commit` | string \| null | Required | Git commit SHA of the run, when known. |
| `run.parent_run_id` | string (uuid) \| null | Required | ID of the run that started this run with `start_workflow_run`. |
| `run.root_run_id` | string (uuid) \| null | Required | ID of the first run in a chain of runs started with `start_workflow_run`. |
| `run.created_at` | string (date-time) | Required | Time the run was created. |
| `job` | object | Required | Job that the event is about. |
| `job.id` | string (uuid) | Required |  |
| `job.key` | string | Required | Job key in the workflow `jobs` map. |
| `job.mode` | string: `one_shot`, `listening` | Required | `listening` for a listening job, otherwise `one_shot`. |
| `job.status` | string: `succeeded`, `failed`, `cancelled`, `skipped` | Required | Final status of the job. |
| `job.status_reason` | string \| null: `dependency_not_completed`, `condition_false`, `default_gate_rejected`, `condition_rejected`, `condition_errored`, `user_cancelled`, `run_cancelled`, `concurrency_superseded`, `timed_out`, `lease_expired`, `provider_lost`, `lifecycle_violation`, `runner_lost`, `output_too_large`, `step_failed`, `unknown`, `output_invalid` | Required | Why the job failed, was cancelled, or was skipped, when known. |
| `job.finished_at` | string (date-time) | Required | Time the job finished. |
| `job.outputs` | object \| null | Required | Job `outputs` of a succeeded job. `null` for other statuses. |

#### `job.completed`

A job completed or was skipped.

```yaml
triggers:
  on_job_completed:
    source: shipfox
    event: job.completed
```