pydo.harness.create_trigger()

Generated on 13 Nov 2026 from pydo version v0.46.0

Usage

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: [email protected]

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
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": "[email protected]",
    "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
{
  "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/agents/triggers in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.