Triggers

Triggers let you run agents automatically — either on a schedule or in response to an incoming webhook. Each trigger is linked to an agent and sends it a message when it fires.

Creating a Trigger

Navigate to Settings > Triggers and click New Trigger. Every trigger requires:

Type: Scheduled or Webhook
Name: A label for the trigger
Agent: Which agent to invoke
Message (optional): The prompt sent to the agent when the trigger fires. For webhooks, this is the default message — it can be overridden in the webhook payload.

Scheduled Triggers

Scheduled triggers run on a recurring basis using cron expressions.

Frequency Options

Preset	Description
Hourly	Runs at the top of every hour
Daily	Runs once per day at a chosen time
Weekdays	Runs Monday through Friday at a chosen time
Weekly	Runs once per week at a chosen time
Custom	Pick specific days of the week or month with a time

Timezone

By default, schedules use your browser’s detected timezone. You can change this under Advanced options in the trigger creation form.

Webhook Triggers

Webhook triggers expose a URL that you can POST to from any external system — CI/CD pipelines, monitoring tools, third-party integrations, or custom scripts. When you create a webhook trigger, you receive a Webhook URL and a Webhook Secret. The secret is only shown once, so save it immediately.

Payload Format

Send a JSON body with these optional fields:

Field	Type	Description
`message`	string	Overrides the trigger’s default message
`payload`	object	Arbitrary data passed as context

{
  "message": "Analyze the latest deployment logs",
  "payload": {
    "environment": "production",
    "commit": "abc123"
  }
}

If you omit message, the trigger’s default message (configured in the UI) is used instead.

Authentication

Every request must include an HMAC-SHA256 signature in the X-Piper-Signature header. The signature is computed over the raw request body using your webhook secret. Header format:

X-Piper-Signature: sha256=<hex_digest>

How to compute the signature:

Take the exact bytes of the request body
Compute HMAC-SHA256(webhook_secret, body)
Hex-encode the result
Prefix with sha256=

Requests with missing or invalid signatures are rejected with a 401 response.

Code Examples

Bash
Python
JavaScript

WEBHOOK_URL="https://api.example.com/v1/webhooks/triggers/YOUR_TRIGGER_ID"
WEBHOOK_SECRET="your_webhook_secret"
BODY='{"message": "Hello from webhook"}'

SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | sed 's/.*= //')

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Piper-Signature: sha256=$SIGNATURE" \
  -d "$BODY"

import hmac, hashlib, json, requests

webhook_url = "https://api.example.com/v1/webhooks/triggers/YOUR_TRIGGER_ID"
webhook_secret = "your_webhook_secret"
body = json.dumps({"message": "Hello from webhook"})

signature = hmac.new(
    webhook_secret.encode(),
    body.encode(),
    hashlib.sha256,
).hexdigest()

response = requests.post(
    webhook_url,
    headers={
        "Content-Type": "application/json",
        "X-Piper-Signature": f"sha256={signature}",
    },
    data=body,
)
print(response.status_code, response.json())

const crypto = require("crypto");

const webhookUrl = "https://api.example.com/v1/webhooks/triggers/YOUR_TRIGGER_ID";
const webhookSecret = "your_webhook_secret";
const body = JSON.stringify({ message: "Hello from webhook" });

const signature = crypto
  .createHmac("sha256", webhookSecret)
  .update(body)
  .digest("hex");

const response = await fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Piper-Signature": `sha256=${signature}`,
  },
  body,
});
console.log(response.status, await response.json());

Rate Limiting

Webhook endpoints are rate-limited to 60 requests per minute per IP address. This is configurable via the RATE_LIMIT_WEBHOOK environment variable in self-hosted deployments.

Error Responses

Status	Meaning
`202 Accepted`	Webhook received and queued for processing
`400 Bad Request`	Invalid JSON payload
`401 Unauthorized`	Missing or invalid `X-Piper-Signature`
`404 Not Found`	Trigger ID does not exist
`409 Conflict`	Trigger is inactive
`429 Too Many Requests`	Rate limit exceeded

Trigger Runs

Every webhook invocation creates a trigger run that you can view in the trigger’s history. Each run shows:

Status: pending, running, success, or error
Duration: How long the agent took to respond
Session link: Navigate directly to the agent’s conversation

Getting Started

Deployment

Integrations

Creating a Trigger

Scheduled Triggers

Frequency Options

Timezone

Webhook Triggers

Payload Format

Authentication

Code Examples

Rate Limiting

Error Responses

Trigger Runs

Getting Started

Deployment

Integrations

​Creating a Trigger

​Scheduled Triggers

​Frequency Options

​Timezone

​Webhook Triggers

​Payload Format

​Authentication

​Code Examples

​Rate Limiting

​Error Responses

​Trigger Runs

Creating a Trigger

Scheduled Triggers

Frequency Options

Timezone

Webhook Triggers

Payload Format

Authentication

Code Examples

Rate Limiting

Error Responses

Trigger Runs