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, and this page is available as Markdown at https://docs.tessl.io/automations/custom-events.md.

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 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:

$ 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.

Post an event from your code

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

$ 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.
  • 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.

{
  "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:

{
  "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.

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:

$ 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 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.

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.
  • Repositories: custom events start runs only for projects whose repository is on GitHub.