Custom Events

Custom Events let your workspace expose webhook URLs that any third-party system can call to trigger workflows. Each event has a unique URL, an optional authentication header, and a free-form JSON payload that your workflows can filter on. Use Custom Events to wire SDLC tools that Overcut does not have a native integration for: CI servers like Jenkins, monitoring platforms like Datadog or Grafana, internal scripts, or any service that can send an HTTP request. If you use GitHub, GitLab, Bitbucket, Azure DevOps, Jira, Linear, ClickUp, or Slack, prefer the native integrations instead. Native integrations handle authentication, event normalization, and reply-target routing for you. Custom Events are for everything else.

The Custom Events page in workspace settings, showing six events with name, description, category, auth mode, scope, and timestamps.

How it works

1. Define the event

A workspace admin creates a Custom Event in the workspace, picks an authentication mode, and decides which projects can react to it.

2. Get a webhook URL

Overcut returns a stable URL on the dispatcher (e.g. https://workflow-dispatcher.overcut.ai/trigger-event/<token>) and, if you chose Bearer or Custom header auth, a one-time secret.

3. Wire your third-party system

Configure the third-party tool to POST a JSON body to that URL when its event fires. Optional query params let you target a specific project or serialize concurrent calls.

4. Trigger workflows

Workflows in the allowed projects pick the event from the trigger picker and filter on payload fields. See Custom Events in workflows.

Permissions

Custom Events are workspace-scoped. The four permissions are granted to workspace admins by default:

Permission	Allows
`customEvent.view`	List events, see webhook URLs
`customEvent.create`	Create a new event
`customEvent.edit`	Edit fields, change allowed projects, rotate the URL token or auth secret
`customEvent.delete`	Delete an event

Granting customEvent.edit lets a user add any project in the workspace to an event’s allowlist. Project admins cannot add their own project to an event’s allowlist on their own.

Create a Custom Event

Open Custom Events

From the workspace sidebar, click Custom Events. The list shows every event defined in the workspace.

Click New event

Fill in the form:

Name: lowercase letters, digits, dashes, underscores. Must be unique in the workspace. Example: deployment_completed. This is the slug your workflows reference.
Description: optional short note for other admins.
Category: required free-form label used to group events in the workflow trigger picker (for example, Deployments, Incidents). The field autocompletes from categories already in use in this workspace.
Auth mode: see Authentication below.
Scope: All projects (default) or Specific projects. With Specific projects, pick which projects can react to this event.

Copy the secret

If you chose Bearer token or Custom header, Overcut shows the generated secret in a green New secret panel: Make sure to copy your new secret now. You won’t be able to see it again. Click Copy secret and store it in the sending system’s configuration.

Copy the webhook URL

The event detail page shows the Webhook URL masked by default. Click Show to reveal it, Copy to copy it to the clipboard, or Example to expand a ready-to-paste curl snippet and use Copy curl.

The auth secret is hashed before it is stored. If you lose it, the only recovery is to rotate (see Rotate below). The webhook URL itself is always retrievable from the event detail page.

Authentication

Pick one auth mode when you create the event. You can change it later.

Bearer token (default)
Custom header
None (URL only)

The sender includes a standard Authorization: Bearer <secret> header on every request.

curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>' \
  -H 'Authorization: Bearer <secret>' \
  -H 'Content-Type: application/json' \
  -d '{"environment":"production","status":"success"}'

Bearer is the right default for almost every integration: scripts, CI jobs, Datadog, Grafana, Jenkins. The secret can be auto-generated by Overcut or pasted in if the sending system already has one to reuse.

The sender includes a header whose name and value you both choose. Use this when the third-party tool forces a specific header (for example, X-API-Key: <secret>).

curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>' \
  -H 'X-API-Key: <secret>' \
  -H 'Content-Type: application/json' \
  -d '{"environment":"production","status":"success"}'

The header name lookup is case-insensitive. The value is compared after trimming whitespace.

No auth header is required. The URL token alone authenticates the request. Use this only for low-risk events from systems inside your network, or for prototypes. Anyone who has the URL can fire the event.

curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>' \
  -H 'Content-Type: application/json' \
  -d '{"environment":"production","status":"success"}'

Target a specific project

Append ?projectId=<id> to fire the event in a single project instead of fanning out to every project the event allows:

curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>?projectId=abc123' \
  -H 'Authorization: Bearer <secret>' \
  -H 'Content-Type: application/json' \
  -d '{"environment":"production"}'

The project must be in the event’s allowlist. If it is not, the dispatcher returns 403 project_not_allowed. If you omit projectId, the event fans out: every project that allows it receives an independent firing evaluated against its own workflows.

Serialize concurrent calls with lockKey

By default, two requests arriving at the same time run two parallel workflow executions. If you want to serialize, pass ?lockKey=<scope>:

# Two deploys to the same service: serialize.
curl ... '?lockKey=service-api'

# Deploys to different services: still parallel.
curl ... '?lockKey=service-web'

Requests sharing the same (event, lockKey) pair run one at a time, and within a short dedupe window collapse into a single queued execution per workflow. Allowed characters: letters, digits, _, ., -, :, up to 128 chars.

A good lockKey is whatever identifies the real-world thing the event is about: the deployment target, the incident ID, the environment name. Calls about the same object serialize, calls about different objects run in parallel.

Improve how runs appear in Overcut

Four optional top-level fields in the payload control how the workflow run looks in Overcut’s run list. They are also still readable from payload.* in trigger conditions.

Field	What it sets	Default if absent	Example
`objectName`	The run’s label in the run list	the event’s slug	`"Deploy #1234 to production"`
`objectNumber`	The run’s object number badge	empty	`"1234"`, `"INC-567"`
`objectUrl`	The click-through link from the run	empty	URL back to the source run
`actor`	The run’s actor (displayed as a Bot)	none	`"deploy-bot"`

Send them like any other payload field:

curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>' \
  -H 'Authorization: Bearer <secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "objectName": "Deploy #1234 to production",
    "objectNumber": "1234",
    "objectUrl": "https://github.com/acme/api/actions/runs/1234",
    "actor": "deploy-bot",
    "environment": "production",
    "status": "success"
  }'

Send events from your tools

The four recipes below cover some common SDLC integrations. They all use the canonical Bearer token auth. For the complete request and response contract, see the Custom Events API reference.

curl (universal baseline)

Any shell script or service that can run curl can fire an event:

curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>' \
  -H 'Authorization: Bearer <secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "objectName": "Nightly backup",
    "status": "success",
    "duration_seconds": 412
  }'

If the sender can only do GET requests, all payload data can ride in the query string instead. Query keys merge into the payload as top-level fields. Body values win on conflicts.

curl 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>?status=success&duration_seconds=412'

Jenkins

Use the HTTP Request plugin in a post-build step or Jenkinsfile stage to notify Overcut when a build finishes. Declarative pipeline:

post {
  always {
    httpRequest(
      httpMode: 'POST',
      url: 'https://workflow-dispatcher.overcut.ai/trigger-event/<token>',
      contentType: 'APPLICATION_JSON',
      customHeaders: [[name: 'Authorization', value: "Bearer ${env.OVERCUT_SECRET}"]],
      requestBody: """{
        "objectName": "${env.JOB_NAME} #${env.BUILD_NUMBER}",
        "objectNumber": "${env.BUILD_NUMBER}",
        "objectUrl": "${env.BUILD_URL}",
        "status": "${currentBuild.currentResult}"
      }"""
    )
  }
}

Store the Overcut secret as a Jenkins credential and inject it via withCredentials so it never lands in a build log.

Datadog monitors

Datadog’s Webhooks integration sends a POST when a monitor triggers. Configure one webhook per Overcut event you want to fire, then reference it with @webhook-<name> in any monitor’s notification message. Webhook configuration (Datadog → Integrations → Webhooks):

URL: https://workflow-dispatcher.overcut.ai/trigger-event/<token>
Custom Headers (JSON):
```
{ "Authorization": "Bearer <secret>" }
```

Payload:

{
  "objectName": "$EVENT_TITLE",
  "objectNumber": "$ID",
  "objectUrl": "$LINK",
  "actor": "datadog",
  "status": "$ALERT_STATUS",
  "priority": "$ALERT_PRIORITY",
  "query": "$ALERT_QUERY"
}

A workflow listening on this event can filter on payload.status == "alert" and read the full Datadog metadata from payload.*.

Grafana Alerting

Configure a Grafana webhook contact point and assign it to a notification policy. Contact point (Alerting → Contact points → New contact point):

Integration: Webhook
URL: https://workflow-dispatcher.overcut.ai/trigger-event/<token>
HTTP method: POST
Authorization Header Scheme: Bearer
Authorization Header Credentials: <secret>

Grafana sends an Alertmanager-shaped JSON body. Workflows read individual alerts from payload.alerts[*]. For richer run-list display, switch to a Custom Payload template and project objectName, objectNumber, and objectUrl into the body.

Rotate the URL token or secret

Both the URL token and the auth secret can be rotated independently from the event detail page.

Rotate URL token: invalidates the current webhook URL and generates a new one. Any sender still using the old URL starts getting 404 token_invalid immediately.
Rotate secret: invalidates the current auth secret and shows the new one in the same one-time New secret panel. The URL keeps working.

When rotating the secret, you can either let Overcut generate a new value or enter one yourself in the New secret (optional) field (useful when the sending system already has a secret you want to reuse).

Rotation takes effect immediately, with no overlap period. Update the sending system before you rotate, or expect a short window of 401 auth_invalid responses.

Change scope or rename

Change scope (All projects ↔ Specific projects, or edit the allowed projects list) takes effect immediately. Workflows in newly-excluded projects silently stop firing for the event.
Rename the event (change its name slug) requires updating the trigger source in any workflow that references the old slug. Trigger picker entries for the old slug stop matching incoming events.

Delete an event

Deleting an event invalidates the URL immediately (the dispatcher returns 404 token_invalid) and stops every workflow that was triggering on the event. Past workflow runs are preserved and continue to show the event’s slug as their trigger; the runs are not retroactively edited.

Next steps

Use a Custom Event in a workflow

Pick the event in the trigger picker, filter on payload.* fields, and access event data in downstream steps.

API reference

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

Get Started

Concepts

Quick Starts

Workflows and Actions

Reference

Integrations

Repositories

How it works

1. Define the event

2. Get a webhook URL

3. Wire your third-party system

4. Trigger workflows

Permissions

Create a Custom Event

Authentication

Target a specific project

Serialize concurrent calls with lockKey

Improve how runs appear in Overcut

Send events from your tools

curl (universal baseline)

Jenkins

Datadog monitors

Grafana Alerting

Rotate the URL token or secret

Change scope or rename

Delete an event

Next steps

Use a Custom Event in a workflow

API reference

Get Started

Concepts

Quick Starts

Workflows and Actions

Reference

Integrations

Repositories

Documentation Index

​How it works

1. Define the event

2. Get a webhook URL

3. Wire your third-party system

4. Trigger workflows

​Permissions

​Create a Custom Event

​Authentication

​Target a specific project

​Serialize concurrent calls with lockKey

​Improve how runs appear in Overcut

​Send events from your tools

​curl (universal baseline)

​Jenkins

​Datadog monitors

​Grafana Alerting

​Rotate the URL token or secret

​Change scope or rename

​Delete an event

​Next steps

Use a Custom Event in a workflow

API reference

How it works

Permissions

Create a Custom Event

Authentication

Target a specific project

Serialize concurrent calls with lockKey

Improve how runs appear in Overcut

Send events from your tools

curl (universal baseline)

Jenkins

Datadog monitors

Grafana Alerting

Rotate the URL token or secret

Change scope or rename

Delete an event

Next steps