---
title: pydo.harness.create_trigger()
description: CreateTrigger creates a webhook or cron trigger.
product: Reference
url: https://docs.digitalocean.com/reference/pydo/reference/harness/create_trigger/
last_updated: "2026-11-20"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# pydo.harness.create_trigger()

Generated on 20 Nov 2026 from `pydo` version [`v0.47.0`](https://github.com/digitalocean/pydo/releases/tag/v0.47.0)

## Usage

```python
client.harness.create_trigger(
    body={
        "kind": "webhook",
        "name": "nightly-deploy-check",
        "session_mode": "fresh",
        ...,
    },
)
```

Returns `JSON` Raises `HttpResponseError`

## Description

Validation is synchronous, so a mistake is a 400/409 at creation, not a silent miss at the first fire. Exactly one of `webhook` / `cron` must be present and match `kind`. kind=cron forbids a `webhook` block and requires a parseable `cron.cron_expr` and a valid IANA `cron.timezone`. session_mode=fresh requires `session_template` (a well-formed agents.yaml Agent manifest) and forbids `bound_session_id`; session_mode=reuse requires `bound_session_id` (an existing team-owned session) and forbids `session_template`. `output.mode` selects the destination block (email/slack), which is stored encrypted. `name` must be unique per team among non-deleted triggers. Triggers do not support persistent workspaces: a `session_template` that names `workspace_id`, and a `bound_session_id` whose session has a workspace, are both refused.

For webhook triggers the response includes `webhook_secret` exactly ONCE - it is never returned again. Cron triggers return no secret and carry a computed `trigger.cron.next_run_at`. The team and user identity are taken from the authenticated principal, never the body.

## Parameters

`kind` string required

How the trigger fires - on an event (webhook) or on a schedule (cron). Immutable after create.

One of: `webhook`, `cron`

`name` string required

Example: `nightly-deploy-check`

Team-unique (among non-deleted triggers) trigger name. Same rules as session names; not UUID-form.

Min length: `1`

Max length: `64`

`session_mode` string required

fresh = a new session is created from the trigger's spec on every firing and destroyed after. reuse = the trigger binds an existing PAUSED session, resumed on each firing and paused after; multiple triggers may bind one session.

One of: `fresh`, `reuse`

`prompt_template` string required

Example: `Review the latest push and summarize risks.`

The prompt sent on each fire. For cron it must not contain payload-interpolation placeholders.

`output` object required

Output-delivery configuration on create/update. Exactly one of email / slack is required for the matching mode and forbidden otherwise; destinations are stored encrypted and never returned.

## Show child properties

`mode` string required

none = nothing pushed; the result stays in run history for self-serve. email = the collected run output is emailed to a configured address. slack = the collected run output is posted to a Slack incoming webhook URL (channel fixed by the webhook at install time).

One of: `none`, `email`, `slack`

`email` string optional

Example: `oncall@example.com`

Destination address; required iff mode=email.

`slack` object optional

Slack destination on create/update. webhook_url is required when mode=slack; must be https://hooks.slack.com/services/...; stored encrypted and never returned.

### Show child properties

`webhook_url` string required

Example: `https://hooks.slack.com/services/T0000/B0000/XXXX`

Slack incoming webhook URL (https://hooks.slack.com/services/...). The channel is bound to this URL at install time.

`session_template` string optional

fresh only. Full agents.yaml Agent manifest (YAML or JSON). Any embedded env values are split out and encrypted server-side.

`bound_session_id` string optional

Example: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

reuse only. UUID of an existing session owned by the team.

`webhook` object optional

webhook block on create. Omitting provider defaults to custom.

## Show child properties

`provider` string optional

Signature-verification scheme applied to a delivery. Omitted on create defaults to custom.

One of: `github`, `gitlab`, `custom`

`cron` object optional

cron block on create.

## Show child properties

`cron_expr` string required

Example: `0 9 * * 1-5`

`timezone` string required

Example: `America/New_York`

IANA timezone.

## Request Sample

## Show Request Sample

```python
import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "kind": "webhook",
  "name": "nightly-deploy-check",
  "session_mode": "fresh",
  "prompt_template": "Review the latest push and summarize risks.",
  "output": {
    "mode": "email",
    "email": "oncall@example.com",
    "slack": {
      "webhook_url": "https://hooks.slack.com/services/T0000/B0000/XXXX"
    }
  },
  "session_template": "",
  "bound_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "webhook": {
    "provider": "github"
  },
  "cron": {
    "cron_expr": "0 9 * * 1-5",
    "timezone": "America/New_York"
  }
}

resp = client.harness.create_trigger(body=req)
```

## Response Example

## Show Response Example

```json
{
  "trigger": {
    "trigger_id": "b1a0c6de-1f2e-4a3b-9c8d-0e1f2a3b4c5d",
    "kind": "webhook",
    "name": "nightly-deploy-check",
    "status": "active",
    "session_mode": "fresh",
    "agent_kind": "AGENT_KIND_UNSPECIFIED",
    "prompt_template": "Review the latest push and summarize risks.",
    "output": {
      "mode": "email",
      "email_configured": true,
      "slack_configured": false
    },
    "session_template": "",
    "bound_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "webhook": {
      "provider": "github",
      "webhook_url": "https://api.digitalocean.com/v2/agents/triggers/b1a0.../webhook"
    },
    "cron": {
      "cron_expr": "0 9 * * 1-5",
      "timezone": "America/New_York",
      "next_run_at": "2026-07-27T13:00:00Z"
    },
    "created_at": "2026-07-27T12:00:00Z",
    "updated_at": "2026-07-27T12:00:00Z"
  },
  "webhook_secret": "whsec_a1b2c3d4e5f6"
}
```

## More Information

See [`/v2/harness-runtime/triggers`](https://docs.digitalocean.com/reference/api/reference/harness-runtime/index.html.md#harness_create_trigger) in the API reference for additional detail on responses, headers, parameters, and more.