Workflow Triggers

Generic workflow triggers let you run any Bosun task in response to external systems. They combine two building blocks:

• Event source connections accept incoming webhook payloads from GitHub, Sentry, or custom sources.
• Workflow triggers filter those payloads, map fields into task inputs, and dispatch the task run.

This guide focuses on the custom (generic) connector that works with any service capable of sending HTTP requests.

When to use generic triggers

• You already have monitoring, ticketing, or CI systems that emit webhooks and want Bosun to remediate the issue automatically.
• You need fine-grained control over which events launch a run, down to JSON fields inside the payload.
• You want to enrich the resulting session with metadata that explains why the automation fired.

Create a webhook source

1. Open Organization Settings → Workflow triggers.
2. Select Create webhook source and provide a descriptive name.
3. Enter a signing secret (required when the source is enabled). Bosun uses it to validate the X-Webhook-Secret header.
4. Save the source. Bosun returns a URL in the form https://<your-host>/webhooks/custom/<ingress_token>.
5. Keep the secret somewhere safe; it is never shown again. Toggle the source off while you stage the rest of the configuration.

Webhook requests must:

• Use POST with Content-Type: application/json.
• Include the shared secret in X-Webhook-Secret.
• Provide an event name via X-Event-Name or by setting event_name in the JSON body.

Example request

curl -X POST "https://bosun.example.com/webhooks/custom/abcd1234" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: s3cr3t" \
  -H "X-Event-Name: incident.created" \
  -H "X-Event-Id: f2c1b5" \
  -d '{
    "event_name": "incident.created",
    "external_event_id": "INC-4421",
    "payload": {
      "customer": "acme-co",
      "severity": "high",
      "service": "payments",
      "ticket_url": "https://tracker.local/incidents/4421"
    }
  }'

X-Event-Id (or external_event_id in the body) makes deduplication deterministic: Bosun drops duplicates that arrive within five minutes.

Build a trigger for the webhook

1. Go to Project → Workflow triggers and pick Create trigger.
2. Choose the webhook source you created earlier and the repository that contains the manifest you want to run.
3. Select the task to execute. Triggers can launch any task in the organization, including public tasks.
4. Set the event filter:
   • Provide an exact event name such as incident.created.
   • Use * to match every event from the connection.
5. Decide whether to enable the trigger immediately. Leaving it disabled lets you finish mappings and simulations without dispatching runs.

Map payload data to task inputs

Many manifests expect inputs like issue numbers, service names, or commit SHAs. Use the Inputs stage to translate webhook payloads into those inputs. Each row contains:

• Input key – the manifest input (for example service_name).
• JSONPath – the path inside the payload (for example $.payload.service). Bosun uses the JsonPath syntax.
• Required – flag missing values as simulation errors and block dispatch.
• Default value – optional fallback if the payload omits the field.

Example configuration for the sample payload above:

[
  { "input_key": "customer", "path": "$.payload.customer", "required": true },
  { "input_key": "service", "path": "$.payload.service", "required": true },
  { "input_key": "ticket_url", "path": "$.payload.ticket_url", "required": false }
]

Bosun stores the resolved input values on the task run exactly as if you had typed them on the Configure Run screen.

Add conditions and metadata

Conditions let you narrow events before they trigger a run. Each rule references a JSONPath and one of three operators:

• eq – matches when the value equals the provided string or number.
• in – matches when the value equals any member of an array (or when an array payload overlaps with the provided array).
• exists – matches when the JSONPath resolves to a value.

For example, to only react to high-severity incidents about the payments service:

[
  { "path": "$.payload.severity", "operator": "eq", "value": "high" },
  { "path": "$.payload.service", "operator": "eq", "value": "payments" }
]

Use the Metadata stage to capture additional payload fields (customer name, ticket URLs, paging IDs, etc.). Metadata appears in the session sidebar and inside the trigger context so teammates can tell why the automation ran.

Test and monitor

• Paste any JSON payload into the Live test panel or select a previously received event to auto-fill the payload.
• Run a simulation to view:
  • Whether conditions matched.
  • Which input mappings resolved values, used defaults, or failed.
  • Which metadata keys were populated.
• The Events tab lists recent webhook deliveries along with status (accepted, matched, dispatched, or failed), any errors, and the task runs launched from the event.
• From an event card you can open the payload, clone it into a new trigger, or inspect delivery logs without hitting the API.

Operational tips

• Use unique X-Event-Id values so Bosun can de-duplicate retries from your webhook sender.
• Disable a trigger (or the entire source) while editing mappings to avoid partial runs.
• Metadata values become part of the run’s trigger context, which appears beside every session in the Bosun UI and via the Sessions API. Use this to link back to tickets, incidents, or upstream dashboards.