Incident.io

To integrate groundcover with incident.io, follow the steps below. Note that you’ll need a Pro incident.io account with API access.

1. Generate an API Key Log in to your incident.io account and create an API key. Make sure it has at least the “Create incidents” permission.

2. Set Up the Webhook in groundcover

   • Set the Webhook URL to: https://api.incident.io/v2/incidents

   • Keep the HTTP method as POST

   • Under Authentication, select API Key Authentication and paste the API key you created in step 1.

3. Create a Workflow Go to Monitors --> Workflows --> Create Workflow, and paste the YAML configuration provided below. Note: The body section is a dictionary of keys that will be sent as a JSON payload to the incident.io API

4. Configure the providers Block In the providers block, replace {{ providers.your-incident-io-integration-name }} with your actual webhook integration name. For example, if you named your integration test-incidentio, the config reference would be: {{ providers.test-incidentio }}\

5. Required Parameters for Creating an Incident When triggering an incident, the following keys are required:

   1. idempotency_key - A unique identifier for the issue (e.g., the issue ID)

   2. visibility - Defines who can see the incident. Example: "public" (you can adjust this based on your preference)

   3. severity_id - The ID of the severity level (not the name). You can retrieve this from the severities list endpoint in incident.io. Replace [severity_id] with your actual value.

   4. name - Optional but recommended for clearer context You can include additional optional parameters as needed. Refer to the incident.io create incident API documentation for the full list of available fields.

Example code for your groundcover workflow:

workflow:
  id: webhook
  description: Sends an API to incident.io endpoint
  triggers:
  - type: alert
  consts:
    description: keep.dictget( {{ alert.annotations }}, "_gc_description", '')
    issue: https://app.groundcover.com/monitors/issues?backendId={{ alert.labels.backend_id }}&selectedObjectId={{ alert.fingerprint }}
    monitor: https://app.groundcover.com/monitors?backendId={{ alert.labels.backend_id }}&selectedObjectId={{ alert.labels._gc_monitor_id }}
    redacted_labels: keep.dict_pop({{alert.labels}}, "_gc_monitor_id", "_gc_monitor_name", "_gc_severity", "backend_id", "grafana_folder", "_gc_issue_header")
    silence: https://app.groundcover.com/monitors/create-silence?keep.replace(keep.join({{ consts.redacted_labels }}, "&", "matcher_"), " ", "+")
    title: keep.dictget( {{ alert.annotations }}, "_gc_issue_header", "{{ alert.alertname }}")
  name: incident-io-workflow
  actions:
  - name: webhook
    provider:
      config: ' {{ providers.your-incident-io-integration-name }} '
      type: webhook
      with:
        body:
          idempotency_key: '{{ alert.fingerprint }}'
          visibility: public
          severity_id: [severity_id]
          name: '{{ alert.alertname }}'
          description: '{{ consts.description }}'

Another example for a conditional groundcover workflow with your incident.io Webhook (based on the monitor severity):

workflow:
  id: webhook
  description: Sends an API to incident.io endpoint
  triggers:
  - type: alert
  consts:
    description: keep.dictget( {{ alert.annotations }}, "_gc_description", '')
    issue: https://app.groundcover.com/monitors/issues?backendId={{ alert.labels.backend_id }}&selectedObjectId={{ alert.fingerprint }}
    monitor: https://app.groundcover.com/monitors?backendId={{ alert.labels.backend_id }}&selectedObjectId={{ alert.labels._gc_monitor_id }}
    redacted_labels: keep.dict_pop({{alert.labels}}, "_gc_monitor_id", "_gc_monitor_name", "_gc_severity", "backend_id", "grafana_folder", "_gc_issue_header")
    silence: https://app.groundcover.com/monitors/create-silence?keep.replace(keep.join({{ consts.redacted_labels }}, "&", "matcher_"), " ", "+")
    title: keep.dictget( {{ alert.annotations }}, "_gc_issue_header", "{{ alert.alertname }}")
  name: incident-io-workflow
  actions:
  - name: webhook-critical
    if: "'{{ alert.annotations._gc_severity }}' == 'S1' or '{{ alert.annotations._gc_severity }}' == 'critical'"
    provider:
      config: ' {{ providers.your-incident-io-integration-name }} '
      type: webhook
      with:
        body:
          idempotency_key: '{{ alert.fingerprint }}'
          visibility: public
          name: "Critical incident happening"
          severity_id: [severity_id_critical]
          summary: 'This is severity: {{ alert.annotations._gc_severity }}'
          description: '{{ consts.description }}'
  - name: webhook-minor
    if: "'{{ alert.annotations._gc_severity }}' == 'S3' or '{{ alert.annotations._gc_severity }}' == 'warning' or '{{ alert.annotations._gc_severity }}' == 'S4' or '{{ alert.annotations._gc_severity }}' == 'info'"
    provider:
      config: ' {{ providers.your-incident-io-integration-name }} '
      type: webhook
      with:
        body:
          idempotency_key: '{{ alert.fingerprint }}'
          visibility: public
          name: "Minor incident started"
          severity_id: [severity_id_minor]
          description: '{{ consts.description }}'