Skip to main content
A trigger tells Pylon what event should activate a pipeline. Every pylon has exactly one trigger, defined under the trigger key in pylon.yaml. Pylon supports two trigger types: webhook for HTTP-driven events and cron for scheduled jobs.

​
Webhook triggers

A webhook trigger listens for an HTTP POST to a specific path on Pylon’s built-in server. When a request arrives at that path, Pylon loads the matching pylon and starts a job. Pylon listens on port 8080 by default. You can change this in ~/.pylon/config.yaml under server.port. 
trigger:
  type: webhook
  path: /sentry-triage

​
Webhook fields

FieldRequiredDescription
typeYesMust be webhook.
pathYesThe URL path Pylon listens on, e.g. /sentry-triage. Must start with /.
secretNoA shared secret used to validate the request signature. Supports ${ENV_VAR} references.
signature_headerNoThe HTTP header containing the HMAC signature, e.g. Sentry-Hook-Signature or X-Hub-Signature-256. Required when secret is set.
public_urlNoOverrides the global server.public_url for this pylon’s displayed webhook URL.

​
HMAC validation

When you set secret and signature_header, Pylon validates the HMAC signature on every incoming request and rejects requests that fail validation. 
trigger:
  type: webhook
  path: /sentry-triage
  secret: "${SENTRY_CLIENT_SECRET}"
  signature_header: Sentry-Hook-Signature
Store secrets in ~/.pylon/.env and reference them with ${VAR_NAME} — Pylon loads this file on startup.

​
Exposing the webhook publicly

Pylon’s server runs locally. To receive webhooks from external services (GitHub, Sentry, etc.), you need to expose it to the internet.
Point your reverse proxy (nginx, Caddy, Traefik) at Pylon’s local port and set public_url in your global config or per-pylon:
# ~/.pylon/config.yaml
server:
  port: 8080
  public_url: https://pylon.example.com

​
Cron triggers

A cron trigger runs a pylon on a schedule, using standard cron expression syntax. 
trigger:
  type: cron
  cron: "0 9 * * 1-5"

​
Cron fields

FieldRequiredDescription
typeYesMust be cron.
cronYesA standard 5-field cron expression.

​
Cron expression format

┌───── minute (0-59)
│ ┌───── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌───── month (1-12)
│ │ │ │ ┌───── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *
Common examples: 
0 9 * * 1-5    # Weekdays at 9am
0 9 * * 1      # Every Monday at 9am
0 */6 * * *    # Every 6 hours
Cron pylons run the agent directly and post results to the configured channel. There is no approval flow for cron triggers — approval: true has no effect when type: cron.

​
Cron example

trigger:
  type: cron
  cron: "0 9 * * 1"  # Every Monday at 9am

workspace:
  type: git-clone
  repo: git@github.com:acme/nexus.git
  ref: main

agent:
  prompt: |
    Audit this codebase for security vulnerabilities, outdated
    dependencies, and code quality issues. Provide a summary report.
  timeout: 30m

channel:
  message: "Weekly codebase audit"

​
Coming soon

The following trigger types are planned but not yet available:
  • Chat command — trigger a pylon from a Telegram or Slack message
  • API call — trigger a pylon via a direct API request with auth