Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt

Use this file to discover all available pages before exploring further.

Once a workspace admin has defined a Custom Event and the event’s allowlist includes your project, the event is available in your workflow’s trigger picker exactly like any built-in trigger. This page covers the workflow-author side: picking the event, filtering on payload fields, and reading event data in agents and actions. For setup, authentication, and the webhook contract, see Custom Events (Integrations) and the API reference.

​
Pick a Custom Event in the trigger picker

Open a workflow

Open any workflow in the current project and select its Trigger container.

Add or edit a trigger card

Click Add trigger (or select an existing trigger card) to open the Properties panel.

Choose the event

Open the Trigger event dropdown. Below the built-in groups (Issue, Pull Request, CI Workflow, Mention, Channel Message, Schedule, Slash Command, Manual), Custom Events appear grouped by their Category. Pick the event slug you want (for example, deployment_completed under Deployments).

Add conditions (optional)

Use the conditions builder to filter on payload fields. See Filter on payload fields below.
Only Custom Events whose allowlist includes the current project appear in that project’s picker. If you expect an event to be available and it isn’t, ask a workspace admin to add the project to the event’s allowlist on the Custom Events page.

​
Filter on payload fields

The webhook body and any query-string parameters are exposed to trigger conditions under payload.*. Use dot notation for nested keys.
The payload.* scope is specific to Custom Events. Built-in event triggers (issue, pull request, CI workflow, etc.) match on context.* fields like context.actor.type or context.repository.name instead. The dispatcher also mirrors the body at context.payload.*, so context.payload.environment and payload.environment resolve to the same value.
For a payload like: 
{
  "environment": "production",
  "status": "success",
  "service": { "name": "api", "region": "us-east-1" }
}
You can write conditions like:
FieldOperatorValueMatches
payload.environmentequalsproductiononly production
payload.statusnotEqualscancelledanything except cancelled
payload.service.nameequalsapionly the api service
payload.service.regionstartsWithus-any US region
Combine multiple conditions with and / or groups. The four well-known meta fields (objectName, objectNumber, objectUrl, actor) are also readable from payload.* even though Overcut also uses them for the run-list display. Comparisons are case-insensitive: payload.status == "Success" matches "SUCCESS" and "success". Missing fields short-circuit to a non-match: a condition on payload.service.region against a payload that has no service object simply does not fire. The full list of operators (equals, notEquals, contains, notContains, startsWith, endsWith, matches, in, notIn) is documented in the Trigger Execution reference.

​
Improve the run’s appearance

Without any payload hints, a Custom Event run shows the event’s slug as its label (for example, deployment_completed) and has no click-through link. To make runs scannable, ask the sender to include the four well-known meta fields:
Caller fieldSetsExample
objectNameRun label in the runs list"Deploy #1234 to production"
objectNumberObject number badge"1234"
objectUrlClick-through link from the runURL back to the source system
actorThe run’s actor (shown as a Bot)"deploy-bot"
These are read by Overcut and still available to your conditions, so a single field like objectName: "Deploy #1234 to production" controls both the display and any rule that filters on it. See Improve how runs appear in Overcut for the sender-side details.

​
Access event data in downstream steps

Once a trigger fires, the standard trigger.* template variables are populated from the well-known meta fields: 
{{trigger.eventType}}            → "custom_event"
{{trigger.triggerObjectName}}    → "Deploy #1234 to production"
{{trigger.triggerObjectNumber}}  → "1234"
{{trigger.triggerObjectUrl}}     → "https://github.com/..."
{{trigger.actor.login}}          → "deploy-bot"
The full payload is available under trigger.payload.*: 
{{trigger.payload.environment}}      → "production"
{{trigger.payload.service.name}}     → "api"
Use these in agent prompts, action parameters, conditional steps, and step outputs exactly like any other trigger variable. See the Event Context Reference for the full list of fields available to a Custom Event workflow.

​
One event, many workflows

The same Custom Event slug can drive any number of workflows in any allowed project. Each workflow evaluates its own trigger conditions independently against the same incoming payload. This is the standard pattern: define one deployment_completed event in the workspace, then have a “post to Slack” workflow, an “open changelog draft” workflow, and a “run smoke tests” workflow each filter for the deployments they care about.

​
Concurrency: avoid duplicate runs

By default, every webhook call produces its own workflow execution: ten POSTs in a second produce ten runs (and ten parallel queued events per matching workflow). When that is wrong, the sender can pass ?lockKey=<scope> to serialize:
  • Requests sharing the same (event, lockKey) run one at a time.
  • Within a short dedupe window, repeats collapse into a single queued execution per workflow.
  • Different lockKey values run in parallel.
This is configured on the sender side, not in the workflow. See Serialize concurrent calls with lockKey.

Custom Events setup

Create an event, get a webhook URL, pick an auth mode, and wire your third-party tools.

API reference

Full request and response contract: every header, query param, error code, and limit.

Event Context Reference

All trigger.* template variables, including the Custom Event fields.

Advanced Trigger Execution

Operator list, event merging, priority queuing, and the Custom Event lock-key formula.