How can external information be written back to Keep and associated with the Alert or Incident?

[minrat]

Keep receives an Alert, and at the same time an Incident is generated. Meanwhile, the Alert is sent via webhook to an external LLM or Agent for RCA analysis. How can the external RCA analysis result be written back to the enriched field of the Alert, or to the Summary of the Incident?

[dosubot[bot]]

Hi @minrat! I'm Dosu and I'm helping the Keep team.

There are two main approaches to write external RCA results back to Keep: direct API calls and Keep Workflows.

---

Option 1: Direct API Calls (from your external LLM/Agent)

Enrich an Alert — POST /alerts/enrich with the X-API-KEY header [1]:

curl -X POST https://<keep-api>/alerts/enrich \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "<alert-fingerprint>",
    "enrichments": {
      "rca_analysis": "Root cause: network timeout in upstream service",
      "rca_remediation": "Restart pod X"
    }
  }'

The enrichments dict accepts arbitrary key-value pairs that get merged into the alert's existing enrichment data [2] [3].

Update an Incident Summary — PUT /incidents/{incident_id} [4]:

curl -X PUT "https://<keep-api>/incidents/<incident-id>?generatedByAi=true" \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_summary": "RCA: Network timeout in upstream service caused cascading failures..."
  }'

The user_summary field maps to the incident summary shown in the UI [5].

---

Option 2: Keep Workflows (Keep calls the external LLM for you)

Instead of having the external system call back, you can define a workflow that triggers on an alert, calls your LLM, and writes the result back — all declaratively:

workflow:
  id: rca-enrichment
  triggers:
    - type: alert
  actions:
    - name: run-rca
      provider:
        type: http
        config: "{{ providers.my-http }}"
        with:
          url: "https://your-llm-service.com/rca"
          method: POST
          body: '{"alert": "{{ alert.name }}", "description": "{{ alert.description }}"}'
          enrich_alert:
            - key: rca_analysis
              value: "{{ steps.run-rca.results.body.analysis }}"

The enrich_alert block on any provider action maps step results back to the alert [6]. There's also enrich_incident for incident-triggered workflows [7]. Keep has built-in support for providers like openai if you want to call an LLM directly from a workflow [8].

---

Authentication: All API calls require the X-API-KEY header. The key needs write:alert scope for enrichment and write:incident scope for incident updates [9]. You can generate an API key from the Keep settings page.

Let me know if you'd like more detail on any of these approaches!

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[minrat]

Hi @ dosubot

How can I obtain the incident_id?

[dosubot[bot]]

@minrat — there are a few ways to get the incident_id depending on your scenario:

1. From the API — Call GET /incidents and the id field in each returned incident object is the UUID you need [1]:

curl -X GET "https://<keep-api>/incidents" \
  -H "X-API-KEY: <your-api-key>"

The response contains items[].id — that's the incident_id [2].

2. From the UI — When you open an incident in the Keep UI, the incident_id is visible directly in the browser URL: /incidents/<incident_id> [3].

3. From a workflow — If your workflow is triggered by an incident event, you can reference the incident using {{ incident.fingerprint }} in your workflow YAML [4]. The full incident object (including its id) is passed as the event payload when a workflow fires on incident creation or update [5].

4. From alert data — When alerts are returned with incident metadata, the associated incident ID(s) are available in the alert's incident field [6].

For your use case (external LLM sends RCA results back), the most practical approach is likely:

• If you're using a Keep workflow to trigger the external analysis, the incident context is already available in the workflow via {{ incident.fingerprint }}.
• If your external system needs to find the incident, call GET /incidents filtered by status or time, or extract the incident ID from the alert data when the webhook fires.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[minrat]

Hi @ dosubot

@ Fingerprint
How can I obtain the fingerprint for an Alert? I tried using {{ alert.fingerprint }}, but I can't get it.