> For AI agents: the complete documentation index is available at https://docs.tessl.io/llms.txt, the full documentation bundle is available at https://docs.tessl.io/llms-full.txt.

# Custom events

:::info

**Takeaways:**

- A custom event is an event you name and post to a project, from your own code with a Tessl API key or from a run with its run key. The project needs nothing set up first.
- A trigger listens for it on `custom:<event>`, such as `custom:deploy.finished`.
- The answer's `outcome` says whether an active trigger matched the event.
- A project accepts about 60 custom events a minute and bodies up to 1 MB.

:::

Some of the work you want a loop to pick up starts in your own systems: a deploy finishing, a message arriving, or a run deciding that another loop should take over. A custom event lets your code or a run start a loop with an event it names, carrying the data the loop needs.

To start a loop from a service that sends webhooks, such as a monitoring tool, use an [event source](https://docs.tessl.io/automations/event-sources.md) instead.

## Before you start

- A Tessl project for a repository on GitHub. A project whose repository isn't on GitHub accepts custom events, but starts no runs.
- A Tessl API key that can post custom events to the project: a workspace key with the `custom_event_sender` role, a workspace key with publisher or higher, or an organization key. `tessl project list` shows the project's ID.

## Use a dedicated key

A sender such as a CI job only needs to post events. Give it a workspace key with the `custom_event_sender` role instead of a publisher key: the workspace's roles give that key no permission except posting custom events to the workspace's projects. You need publisher or higher in the workspace to create one.

To create the key in the web app, open the workspace's **Settings**, then **API keys**, select **Create new key**, and choose the **Custom event sender** role.

To create it with the CLI:

```shell-session
$ tessl api-key create --workspace engteam --name "deploy-events" --role custom_event_sender --ttl 1y
```

A key with this role starts runs of the project's `custom:` triggers, with a payload it chooses. Treat it as a credential that can start that work. See [Roles](https://docs.tessl.io/administrators/roles.md#the-custom_event_sender-api-key-role).

## Post an event from your code

Post the event to `POST /v1/projects/{projectId}/custom-events`:

```shell-session
$ curl -X POST "https://api.tessl.io/v1/projects/$PROJECT_ID/custom-events" \
    -H "Authorization: Bearer $TESSL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "event": "deploy.finished",
      "deliveryId": "deploy-4821",
      "payload": { "service": "checkout", "environment": "production" }
    }'
```

For an organization on the EU region, use `https://api.eu.tessl.io`.

The body has 3 fields:

- `event` (string, required): the event's name. It starts with a letter and holds only letters, digits, `_`, and `.`, up to 256 characters.
- `deliveryId` (string, required): your id for this event, 1 to 128 characters. See [Delivery ids and retries](#delivery-ids-and-retries).
- `payload` (JSON object, optional): the data a trigger reads as `event.<path>`.

The event reaches this project alone, and a run it starts runs as the project's automation.

## Write a trigger

A trigger listens for the event on `custom:<event>`, filters on the payload with `when`, and passes payload values to the action with `{{ event.<path> }}`, as for any other provider. In a trigger, `event.` is the `payload` you posted.

```json
{
  "actions": {
    "smoke-check": {
      "skill": "engteam/deploy-checks#smoke-check",
      "params": { "SERVICE": "string" }
    }
  },
  "triggers": {
    "after-deploy": {
      "on": ["custom:deploy.finished"],
      "when": { "event.environment": "production" },
      "action": {
        "use": "smoke-check",
        "inputs": { "SERVICE": "{{ event.service }}" }
      },
      "concurrency": { "keys": ["deploy-{{ event.service }}"] }
    }
  }
}
```

One trigger can list several events that share the part of their name before the first dot, such as `custom:deploy.started` and `custom:deploy.finished`. It can't list events that don't, such as `custom:deploy.finished` and `custom:build.finished`; write a trigger for each instead. An event whose payload lacks a field the trigger's `inputs`, `instructions`, or concurrency keys read starts no run.

## The answer

The project answers `202` with the event as a trigger names it and an `outcome`:

```json
{
  "data": {
    "id": "...",
    "type": "custom-event",
    "attributes": {
      "projectId": "...",
      "event": "custom:deploy.finished",
      "deliveryId": "deploy-4821",
      "outcome": "accepted"
    }
  }
}
```

- `accepted`: an active trigger matches the event by its name and its `when` conditions, or the project already received the same `deliveryId`, which then starts nothing again.
- `ignored`: no active trigger matches the event, including when a trigger listens for it but its `when` doesn't match, or its loop is paused. Nothing is kept, so the same `deliveryId` can be sent again.

An `accepted` event's runs start on their own, and may begin before the answer arrives. To see a run, open the loop's page.

Other answers:

- `400`: the body breaks a rule above.
- `403`: the key can't post custom events to the project, which answers `Forbidden`, or a run key is refused, which answers with the reason.
- `404`: no such project, or the project's workspace is archived.
- `413` and `429`: see [Limits](#limits).

## Post an event from a run

A run can start other loops in its own project by posting a custom event with its run key. Every run has the key in `TESSL_TOKEN`, its project's ID in `TESSL_PROJECT_ID`, its own ID in `TESSL_LAUNCH_RUN_ID`, and the API host for its region in `TESSL_API_BASE_URL`:

```shell-session
$ curl -X POST "$TESSL_API_BASE_URL/v1/projects/$TESSL_PROJECT_ID/custom-events" \
    -H "Authorization: Bearer $TESSL_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "event": "review.requested", "deliveryId": "'"$TESSL_LAUNCH_RUN_ID"'-review.requested", "payload": { "branch": "fix-login" } }'
```

The `deliveryId` joins the run's ID and the event's name, so it is unique per event name per run, not per event, and a retry of the same event has the same one. The project deduplicates on `deliveryId` alone: a run that posts `review.requested` twice, for two branches, sends the same id twice, and the second answers `accepted` and starts nothing. A run that posts the same event more than once must add something that tells those events apart to the id, such as the branch.

A run key can post only:

- to the run's own project,
- while the run is still running,
- when the run's [environment](https://docs.tessl.io/schedules/environments.md) allows loops to start other loops in the project, the `actionTrigger: project` setting. That setting lets the run trigger its own project's declared actions and post custom events to its own project.

Otherwise the request is refused with `403` and the reason. A run that an event from a run starts records the sending run as its parent, so its cost is counted with the run that started it.

## Chains of runs

Nothing limits how many runs can start one another with custom events. A loop whose runs post the event that starts it runs until something stops it, so give such a chain an end condition in its `when` or its skill. The project's rate limit is the only brake.

## Delivery ids and retries

A project records each custom event that an active trigger matches under its `deliveryId`. An event with a `deliveryId` the project already recorded starts nothing again, whatever its name, so your code can retry safely. Use an id that stays the same when you retry the same event, and differs for every other event you post to the project. The same id posted to another project is a different event.

An event that no active trigger matches isn't recorded, whether no trigger listens for it or it fails the `when` of every trigger that does. A later event with the same `deliveryId` is matched afresh and can start a run. An event that arrives while its loops are paused is dropped and not recorded. See [Stop, remove, and move loops](https://docs.tessl.io/automations/stop-and-change-loops.md).

## Limits

- **Rate:** a project accepts about 60 custom events a minute. Past that, it answers `429`. This limit is separate from the project's event sources.
- **Body size:** up to 1 MB. Past that, the project answers `413`.
- **Chains:** no limit on how many runs start one another. See [Chains of runs](#chains-of-runs).
- **Repositories:** custom events start runs only for projects whose repository is on GitHub.

## Related pages

- [Event sources](https://docs.tessl.io/automations/event-sources.md): start loops from a service that sends webhooks
- [Automations overview](https://docs.tessl.io/automations/overview.md): how loops, actions, triggers, and runs fit together
- [Actions, triggers, and schedules](https://docs.tessl.io/reference/actions-triggers-schedules.md#triggers): the `triggers` block, `when`, and `concurrency`
- [Environments](https://docs.tessl.io/schedules/environments.md): where the `actionTrigger` setting lives
