Create Workflow

Creates a new workflow for alert handling and notifications. Workflows define how alerts are processed and routed to various integrations like Slack, PagerDuty, webhooks, etc.

Endpoint

POST /api/workflows/create

Authentication

This endpoint requires API key authentication.

Headers

Header	Value	Description
Authorization	Bearer <YOUR_API_KEY>	Your groundcover API key
Content-Type	text/plain	The request body should be raw YAML

Request Body

The request body should contain raw YAML defining the workflow configuration. The YAML structure should include:

• id: Unique identifier for the workflow

• description: Human-readable description

• triggers: Array of trigger conditions

• actions: Array of actions to perform when triggered

• name: Display name for the workflow

• consts (optional): Constants and helper variables

Example Request

curl -L \
  --request POST \
  --url 'https://api.groundcover.com/api/workflows/create' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: text/plain' \
  --data 'id: example-workflow
description: Example workflow for API documentation
triggers:
- type: alert
  filters:
  - key: annotations.example-workflow
    value: enabled
name: example-workflow
consts:
  severity: keep.dictget({{ alert.annotations }}, "_gc_severity", "info")
  title: keep.dictget({{ alert.annotations }}, "_gc_issue_header", "{{ alert.alertname }}")
actions:
- name: webhook-action
  provider:
    type: webhook
    config: "{{ providers.webhook-provider }}"
    with:
      body:
        alert_name: "{{ consts.title }}"
        severity: "{{ consts.severity }}"'

Response

{
  "workflow_id": "xxxxx-xxxx-xxxxx-xxxx-xxxxx",
  "status": "created",
  "revision": 1
}

Workflow YAML Structure

Basic Structure

id: workflow-id
description: Workflow description
triggers:
  - type: alert
    filters:
      - key: filter-key
        value: filter-value
name: workflow-name
consts:
  variable_name: value
actions:
  - name: action-name
    provider:
      type: provider-type
      config: provider-config
      with:
        action-specific-parameters

Choosing Integration Providers

To route alerts to a specific integration (Slack, PagerDuty, webhook, etc.), use the config field in the provider section to reference your configured integration by name.

Example: Slack Integration

actions:
- if: '{{ alert.status }} == "firing"'
  name: slack-action-firing
  provider:
    config: '{{ providers.integration-name }}'
    type: slack
    with:
      attachments:
      - color: '#FF0000'
        footer: 'groundcover.com'
        footer_icon: 'https://app.groundcover.com/favicon.ico'
        text: 'Alert details here'
        title: 'Firing: {{ alert.alertname }}'
        ts: keep.utcnowtimestamp()
        type: plain_text
      message: ' '

Provider Configuration

• config: '{{ providers.integration-name }}' - References a specific integration you've configured in groundcover

• type - Specifies the integration type (slack, webhook, pagerduty, opsgenie)

• Replace integration-name with your actual integration name.

The integration name must match the name of an integration you've previously configured in your groundcover workspace.

References

For workflow examples and advanced configurations, see the groundcover workflow examples documentation.