diff --git a/docs/configuration/exporting/send-events-api.rst b/docs/configuration/exporting/send-events-api.rst deleted file mode 100644 index 4fe9b94dc..000000000 --- a/docs/configuration/exporting/send-events-api.rst +++ /dev/null @@ -1,191 +0,0 @@ -Send Events API -================ - -Send alerts from your monitoring system to Robusta through a single webhook endpoint. - -This is the recommended ingestion path for new integrations. The legacy :doc:`Send Alerts API ` remains available for existing customers. - -.. toctree:: - :maxdepth: 1 - :hidden: - - send-events/alertmanager - send-events/aws-cloudwatch - send-events/azure-monitor - send-events/datadog - send-events/dynatrace - send-events/gcp-monitoring - send-events/grafana - send-events/nagios - send-events/newrelic - send-events/opsgenie - send-events/pagerduty - send-events/sentry - send-events/solarwinds - send-events/splunk - -Endpoint --------- - -.. code-block:: - - POST https://api.robusta.dev/webhooks?type=alert&origin=&account_id= - -Query Parameters ----------------- - -.. list-table:: - :widths: 20 70 - :header-rows: 1 - - * - Parameter - - Description - * - ``type`` - - Must be ``alert``. - * - ``origin`` - - Identifies the monitoring product. Must be one of the supported origins listed under `Integrations`_ below. - * - ``account_id`` - - Your Robusta account ID, found in ``generated_values.yaml``. - -Authentication --------------- - -Send your Robusta API key as a Bearer token. Generate keys in the Robusta UI under **Settings → API Keys → New API Key**. - -.. code-block:: - - Authorization: Bearer - -The key must be scoped to the ``account_id`` query parameter. Mismatches return ``401``. - -Example Request ---------------- - -.. code-block:: bash - - curl --location --request POST \ - 'https://api.robusta.dev/webhooks?type=alert&origin=datadog&account_id=ACCOUNT_ID' \ - --header 'Authorization: Bearer API_KEY' \ - --header 'Content-Type: application/json' \ - --data-raw '{ "title": "High error rate", "severity": "high" }' - -Response --------- - -A successful request returns ``200`` with the ID of the stored event: - -.. code-block:: json - - { "id": "8f1b...e21" } - -Errors: - -* ``400`` — missing or empty ``account_id``, ``origin``, or ``type``; invalid ``type`` value. -* ``401`` — invalid or out-of-scope API key. -* ``429`` — rate limit exceeded (300 requests per 5-minute window per account). -* ``503`` — transient storage failure; vendors should retry. - -Integrations ------------- - -Pick your monitoring system below for step-by-step instructions. Each page provides the URL to paste into your vendor's webhook configuration along with the API key. - -Prometheus & AlertManager -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` AlertManager - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/alertmanager - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Grafana - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/grafana - :link-type: doc - -APM & Observability -~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` Datadog - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/datadog - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` New Relic - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/newrelic - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Dynatrace - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/dynatrace - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Splunk - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/splunk - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Sentry - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/sentry - :link-type: doc - -Cloud Provider Monitoring -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`server;1em;` GCP Cloud Monitoring - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/gcp-monitoring - :link-type: doc - - .. grid-item-card:: :octicon:`server;1em;` Azure Monitor - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/azure-monitor - :link-type: doc - - .. grid-item-card:: :octicon:`server;1em;` AWS CloudWatch - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/aws-cloudwatch - :link-type: doc - -Incident Management -~~~~~~~~~~~~~~~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` PagerDuty - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/pagerduty - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` Opsgenie - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/opsgenie - :link-type: doc - -Other -~~~~~~ - -.. grid:: 1 1 2 3 - :gutter: 3 - - .. grid-item-card:: :octicon:`pulse;1em;` Nagios - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/nagios - :link-type: doc - - .. grid-item-card:: :octicon:`pulse;1em;` SolarWinds - :class-card: sd-bg-light sd-bg-text-light - :link: send-events/solarwinds - :link-type: doc diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index 0173cbf02..2963e4fad 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -9,6 +9,7 @@ Connect your monitoring system to Robusta, to enrich alerts and apply automation :maxdepth: 1 :hidden: + webhooks/send-events-api exporting/send-alerts-api exporting/configuration-changes-api alertmanager-integration/outofcluster-prometheus @@ -37,14 +38,22 @@ Programmatic Integration .. grid:: 1 1 2 3 :gutter: 3 - .. grid-item-card:: :octicon:`code;1em;` Send Alerts API + .. grid-item-card:: :octicon:`code;1em;` Send Events API + :class-card: sd-bg-light sd-bg-text-light + :link: webhooks/send-events-api + :link-type: doc + + Recommended. Send alerts and changes through the single + ``/webhooks`` ingestion endpoint. + + .. grid-item-card:: :octicon:`code;1em;` Send Alerts API (legacy) :class-card: sd-bg-light sd-bg-text-light :link: exporting/send-alerts-api :link-type: doc Send alerts programmatically via the legacy ``/api/alerts`` REST endpoint. - .. grid-item-card:: :octicon:`code;1em;` Configuration Changes API + .. grid-item-card:: :octicon:`code;1em;` Configuration Changes API (legacy) :class-card: sd-bg-light sd-bg-text-light :link: exporting/configuration-changes-api :link-type: doc diff --git a/docs/configuration/exporting/send-events/alertmanager.rst b/docs/configuration/webhooks/alerts/alertmanager.rst similarity index 100% rename from docs/configuration/exporting/send-events/alertmanager.rst rename to docs/configuration/webhooks/alerts/alertmanager.rst diff --git a/docs/configuration/exporting/send-events/aws-cloudwatch.rst b/docs/configuration/webhooks/alerts/aws-cloudwatch.rst similarity index 100% rename from docs/configuration/exporting/send-events/aws-cloudwatch.rst rename to docs/configuration/webhooks/alerts/aws-cloudwatch.rst diff --git a/docs/configuration/exporting/send-events/azure-monitor.rst b/docs/configuration/webhooks/alerts/azure-monitor.rst similarity index 100% rename from docs/configuration/exporting/send-events/azure-monitor.rst rename to docs/configuration/webhooks/alerts/azure-monitor.rst diff --git a/docs/configuration/exporting/send-events/datadog.rst b/docs/configuration/webhooks/alerts/datadog.rst similarity index 100% rename from docs/configuration/exporting/send-events/datadog.rst rename to docs/configuration/webhooks/alerts/datadog.rst diff --git a/docs/configuration/exporting/send-events/dynatrace.rst b/docs/configuration/webhooks/alerts/dynatrace.rst similarity index 100% rename from docs/configuration/exporting/send-events/dynatrace.rst rename to docs/configuration/webhooks/alerts/dynatrace.rst diff --git a/docs/configuration/exporting/send-events/gcp-monitoring.rst b/docs/configuration/webhooks/alerts/gcp-monitoring.rst similarity index 100% rename from docs/configuration/exporting/send-events/gcp-monitoring.rst rename to docs/configuration/webhooks/alerts/gcp-monitoring.rst diff --git a/docs/configuration/exporting/send-events/grafana.rst b/docs/configuration/webhooks/alerts/grafana.rst similarity index 100% rename from docs/configuration/exporting/send-events/grafana.rst rename to docs/configuration/webhooks/alerts/grafana.rst diff --git a/docs/configuration/exporting/send-events/nagios.rst b/docs/configuration/webhooks/alerts/nagios.rst similarity index 100% rename from docs/configuration/exporting/send-events/nagios.rst rename to docs/configuration/webhooks/alerts/nagios.rst diff --git a/docs/configuration/exporting/send-events/newrelic.rst b/docs/configuration/webhooks/alerts/newrelic.rst similarity index 100% rename from docs/configuration/exporting/send-events/newrelic.rst rename to docs/configuration/webhooks/alerts/newrelic.rst diff --git a/docs/configuration/exporting/send-events/opsgenie.rst b/docs/configuration/webhooks/alerts/opsgenie.rst similarity index 100% rename from docs/configuration/exporting/send-events/opsgenie.rst rename to docs/configuration/webhooks/alerts/opsgenie.rst diff --git a/docs/configuration/exporting/send-events/pagerduty.rst b/docs/configuration/webhooks/alerts/pagerduty.rst similarity index 100% rename from docs/configuration/exporting/send-events/pagerduty.rst rename to docs/configuration/webhooks/alerts/pagerduty.rst diff --git a/docs/configuration/exporting/send-events/sentry.rst b/docs/configuration/webhooks/alerts/sentry.rst similarity index 100% rename from docs/configuration/exporting/send-events/sentry.rst rename to docs/configuration/webhooks/alerts/sentry.rst diff --git a/docs/configuration/exporting/send-events/solarwinds.rst b/docs/configuration/webhooks/alerts/solarwinds.rst similarity index 100% rename from docs/configuration/exporting/send-events/solarwinds.rst rename to docs/configuration/webhooks/alerts/solarwinds.rst diff --git a/docs/configuration/exporting/send-events/splunk.rst b/docs/configuration/webhooks/alerts/splunk.rst similarity index 100% rename from docs/configuration/exporting/send-events/splunk.rst rename to docs/configuration/webhooks/alerts/splunk.rst diff --git a/docs/configuration/webhooks/changes/argocd.rst b/docs/configuration/webhooks/changes/argocd.rst new file mode 100644 index 000000000..04d20462c --- /dev/null +++ b/docs/configuration/webhooks/changes/argocd.rst @@ -0,0 +1,108 @@ +Argo CD +======== + +Forward Argo CD application sync events to Robusta so HolmesGPT can +correlate deployments with alert spikes. + +Prerequisites +------------- + +* A Robusta account with API access. +* Your Robusta ``account_id``, found in ``generated_values.yaml``. +* A Robusta API key with ``Read/Write`` access to alerts. +* `argocd-notifications-cm` installed in your Argo CD cluster (ships + with Argo CD 2.3+). + +Webhook URL +----------- + +.. code-block:: + + https://api.robusta.dev/webhooks?type=change&origin=argocd&account_id= + +Configure Argo CD +----------------- + +Add a Robusta webhook service and a notification template to +``argocd-notifications-cm``: + +.. code-block:: yaml + + apiVersion: v1 + kind: ConfigMap + metadata: + name: argocd-notifications-cm + data: + service.webhook.robusta: | + url: https://api.robusta.dev/webhooks?type=change&origin=argocd&account_id= + headers: + - name: Authorization + value: "Bearer " + - name: Content-Type + value: application/json + template.app-change: | + webhook: + robusta: + method: POST + body: | + { + "app": "{{.app.metadata.name}}", + "namespace": "{{.app.metadata.namespace}}", + "project": "{{.app.spec.project}}", + "syncStatus": "{{.app.status.sync.status}}", + "healthStatus": "{{.app.status.health.status}}", + "revision": "{{.app.status.sync.revision}}", + "previousRevision": "{{(index .app.status.history (sub (len .app.status.history) 1)).revision}}", + "repo": "{{.app.spec.source.repoURL}}", + "path": "{{.app.spec.source.path}}", + "cluster": "{{.app.spec.destination.name}}", + "destNamespace": "{{.app.spec.destination.namespace}}", + "operation": "{{.app.status.operationState.phase}}", + "operationMessage": "{{.app.status.operationState.message}}", + "startedAt": "{{.app.status.operationState.startedAt}}", + "finishedAt": "{{.app.status.operationState.finishedAt}}" + } + trigger.on-sync-succeeded: | + - when: app.status.operationState.phase in ['Succeeded'] + send: [app-change] + +Subscribe the trigger on the Application: + +.. code-block:: yaml + + metadata: + annotations: + notifications.argoproj.io/subscribe.on-sync-succeeded.robusta: "" + +Example Payload +--------------- + +After Argo CD substitutes the template variables, Robusta receives: + +.. code-block:: json + + { + "app": "checkout", + "namespace": "argocd", + "project": "default", + "syncStatus": "Synced", + "healthStatus": "Healthy", + "revision": "abc123", + "previousRevision": "def456", + "repo": "https://github.com/acme/checkout", + "path": "deploy/", + "cluster": "prod-eu-1", + "destNamespace": "default", + "operation": "Succeeded", + "operationMessage": "sync completed" + } + +The parser produces a ``configuration_change`` Issue scoped to the +ArgoCD application, with a ``diff`` evidence row contrasting the +previous and current revisions. + +Test the Integration +-------------------- + +Trigger a manual sync from the Argo CD UI. The event should appear on +the Robusta timeline within a few seconds. diff --git a/docs/configuration/webhooks/changes/github.rst b/docs/configuration/webhooks/changes/github.rst new file mode 100644 index 000000000..4518ce5ad --- /dev/null +++ b/docs/configuration/webhooks/changes/github.rst @@ -0,0 +1,93 @@ +GitHub +======= + +Forward GitHub events (pushes, pull requests, releases, deployments) to +Robusta so HolmesGPT can correlate code changes with alert spikes. + +Prerequisites +------------- + +* A Robusta account with API access. +* Your Robusta ``account_id``, found in ``generated_values.yaml``. +* A Robusta API key with ``Read/Write`` access to alerts. +* Repository admin access on the GitHub repository you want to track. + +Webhook URL +----------- + +.. code-block:: + + https://api.robusta.dev/webhooks?type=change&origin=github&account_id= + +Configure GitHub +---------------- + +In your GitHub repository: + +1. Open **Settings → Webhooks → Add webhook**. +2. **Payload URL**: paste the webhook URL above. +3. **Content type**: ``application/json``. +4. **Secret**: leave empty — Robusta authenticates by API key, not by HMAC. +5. **SSL verification**: keep enabled. +6. Under **Which events would you like to trigger this webhook?**, + select **Let me select individual events** and tick: + + * **Pushes** (commits to any branch) + * **Pull requests** (open/close/merge) + * **Releases** + * **Deployments** (optional, if you use GitHub Deployments) +7. **Active**: checked. **Save**. + +GitHub does not support custom request headers on webhooks. Pass the +Robusta API key on the URL instead: + +.. code-block:: + + https://api.robusta.dev/webhooks?type=change&origin=github&account_id=&token= + +Example Payload (push) +---------------------- + +.. code-block:: json + + { + "ref": "refs/heads/main", + "before": "abc...", + "after": "def...", + "repository": { "full_name": "acme/checkout" }, + "sender": { "login": "jane" }, + "commits": [ + { "id": "abcdef1", "message": "fix checkout race" } + ], + "compare": "https://github.com/acme/checkout/compare/abc...def" + } + +Supported Events +---------------- + +The parser recognizes the four most common event shapes: + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Event + - What lands on the timeline + * - ``push`` + - ``GitHub push: @``; commits listed in description. + * - ``pull_request`` + - ``GitHub PR # : ``; base / head SHAs in diff. + * - ``release`` + - ``GitHub release <name> (<action>)``; release notes in description. + * - ``deployment`` + - ``GitHub deployment to <env>: <repo>@<ref>``. + +Other event types fall through to the generic change parser — they're +still stored and visible in the Delivery Log, just without a per-event +mapping. + +Test the Integration +-------------------- + +Push a commit (or create a draft release) on the configured repository. +The event should appear on the Robusta timeline within a few seconds. diff --git a/docs/configuration/webhooks/changes/launchdarkly.rst b/docs/configuration/webhooks/changes/launchdarkly.rst new file mode 100644 index 000000000..b66b9bb5d --- /dev/null +++ b/docs/configuration/webhooks/changes/launchdarkly.rst @@ -0,0 +1,69 @@ +LaunchDarkly +============= + +Forward LaunchDarkly feature-flag changes to Robusta so HolmesGPT can +correlate flag flips with alert spikes. + +Prerequisites +------------- + +* A Robusta account with API access. +* Your Robusta ``account_id``, found in ``generated_values.yaml``. +* A Robusta API key with ``Read/Write`` access to alerts, generated under **Settings → API Keys → New API Key**. + +Webhook URL +----------- + +.. code-block:: + + https://api.robusta.dev/webhooks?type=change&origin=launchdarkly&account_id=<ACCOUNT_ID> + +Configure LaunchDarkly +---------------------- + +In the LaunchDarkly UI: + +1. Open **Integrations → Webhooks** and click **Add integration**. +2. Set **URL** to the webhook URL above. +3. Add a custom header ``Authorization`` with value ``Bearer <ROBUSTA_API_KEY>``. +4. Optionally narrow the **Policy** so only flag changes from the + environments you care about are sent. +5. Save. + +LaunchDarkly's default JSON payload is parsed out of the box — no +template is required. + +Example Payload +--------------- + +.. code-block:: json + + { + "kind": "flag", + "name": "beta-checkout", + "title": "LaunchDarkly Flag Change: beta-checkout", + "titleVerb": "updated", + "description": "enabled in production", + "target": {"name": "beta-checkout"}, + "parent": {"name": "production"}, + "previousVersion": {"environments": {"production": {"on": false}}}, + "currentVersion": {"environments": {"production": {"on": true}}}, + "member": { + "firstName": "Jane", + "lastName": "Doe", + "email": "jane@example.com" + } + } + +The parser produces one ``Issues`` row with ``finding_type = +configuration_change`` plus a ``diff`` evidence row showing the before/after +JSON of the flag in the affected environment, a ``markdown`` summary +block, and the standard ``alert_raw_data`` / ``incoming_event_ref`` +evidences. + +Test the Integration +-------------------- + +Trigger a small change to any flag in your LaunchDarkly project. The +event should appear on the Robusta timeline within a few seconds — open +the **Delivery Log** UI to confirm ``parse_status = parsed``. diff --git a/docs/configuration/webhooks/send-alerts-api.rst b/docs/configuration/webhooks/send-alerts-api.rst new file mode 100644 index 000000000..67cb8bd22 --- /dev/null +++ b/docs/configuration/webhooks/send-alerts-api.rst @@ -0,0 +1,135 @@ +Send Alerts API +================ + +Forward alerts from your monitoring system to Robusta via the webhook +endpoint. Pick your monitoring system below for step-by-step +configuration instructions. + +Endpoint +-------- + +.. code-block:: + + POST https://api.robusta.dev/webhooks?type=alert&origin=<ORIGIN>&account_id=<ACCOUNT_ID> + +See :doc:`send-events-api` for query parameters, authentication, and +error codes. + +.. toctree:: + :maxdepth: 1 + :hidden: + + alerts/alertmanager + alerts/aws-cloudwatch + alerts/azure-monitor + alerts/datadog + alerts/dynatrace + alerts/gcp-monitoring + alerts/grafana + alerts/nagios + alerts/newrelic + alerts/opsgenie + alerts/pagerduty + alerts/sentry + alerts/solarwinds + alerts/splunk + +Prometheus & AlertManager +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`pulse;1em;` AlertManager + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/alertmanager + :link-type: doc + + .. grid-item-card:: :octicon:`pulse;1em;` Grafana + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/grafana + :link-type: doc + +APM & Observability +~~~~~~~~~~~~~~~~~~~~ + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`pulse;1em;` Datadog + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/datadog + :link-type: doc + + .. grid-item-card:: :octicon:`pulse;1em;` New Relic + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/newrelic + :link-type: doc + + .. grid-item-card:: :octicon:`pulse;1em;` Dynatrace + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/dynatrace + :link-type: doc + + .. grid-item-card:: :octicon:`pulse;1em;` Splunk + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/splunk + :link-type: doc + + .. grid-item-card:: :octicon:`pulse;1em;` Sentry + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/sentry + :link-type: doc + +Cloud Provider Monitoring +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`server;1em;` GCP Cloud Monitoring + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/gcp-monitoring + :link-type: doc + + .. grid-item-card:: :octicon:`server;1em;` Azure Monitor + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/azure-monitor + :link-type: doc + + .. grid-item-card:: :octicon:`server;1em;` AWS CloudWatch + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/aws-cloudwatch + :link-type: doc + +Incident Management +~~~~~~~~~~~~~~~~~~~~ + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`pulse;1em;` PagerDuty + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/pagerduty + :link-type: doc + + .. grid-item-card:: :octicon:`pulse;1em;` Opsgenie + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/opsgenie + :link-type: doc + +Other +~~~~~~ + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`pulse;1em;` Nagios + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/nagios + :link-type: doc + + .. grid-item-card:: :octicon:`pulse;1em;` SolarWinds + :class-card: sd-bg-light sd-bg-text-light + :link: alerts/solarwinds + :link-type: doc diff --git a/docs/configuration/webhooks/send-changes-api.rst b/docs/configuration/webhooks/send-changes-api.rst new file mode 100644 index 000000000..a993eaf9f --- /dev/null +++ b/docs/configuration/webhooks/send-changes-api.rst @@ -0,0 +1,52 @@ +Send Changes API +================= + +Forward configuration, feature-flag, and deployment changes to Robusta +via the webhook endpoint. Change events surface alongside alerts on the +issue timeline so HolmesGPT can correlate "what changed" with "what +broke". + +Endpoint +-------- + +.. code-block:: + + POST https://api.robusta.dev/webhooks?type=change&origin=<ORIGIN>&account_id=<ACCOUNT_ID> + +See :doc:`send-events-api` for query parameters, authentication, and +error codes. + +.. toctree:: + :maxdepth: 1 + :hidden: + + changes/launchdarkly + changes/argocd + changes/github + +Feature Flags +~~~~~~~~~~~~~ + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`toggle-switch;1em;` LaunchDarkly + :class-card: sd-bg-light sd-bg-text-light + :link: changes/launchdarkly + :link-type: doc + +GitOps & Deployments +~~~~~~~~~~~~~~~~~~~~ + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`rocket;1em;` Argo CD + :class-card: sd-bg-light sd-bg-text-light + :link: changes/argocd + :link-type: doc + + .. grid-item-card:: :octicon:`mark-github;1em;` GitHub + :class-card: sd-bg-light sd-bg-text-light + :link: changes/github + :link-type: doc diff --git a/docs/configuration/webhooks/send-events-api.rst b/docs/configuration/webhooks/send-events-api.rst new file mode 100644 index 000000000..9c4218173 --- /dev/null +++ b/docs/configuration/webhooks/send-events-api.rst @@ -0,0 +1,123 @@ +Send Events API +================ + +Send events from your monitoring, feature-flag, and deployment systems +to Robusta through a single webhook endpoint. Events come in two +flavors today: + +* **Alerts** — events that warrant investigation (Prometheus, + Datadog, PagerDuty, etc.). See :doc:`send-alerts-api`. +* **Changes** — configuration / deployment changes that correlate with + alerts (LaunchDarkly, Argo CD, GitHub). See :doc:`send-changes-api`. + +This is the recommended ingestion path for new integrations. The +legacy :doc:`/api/alerts </configuration/exporting/send-alerts-api>` and +:doc:`/api/config-changes </configuration/exporting/configuration-changes-api>` +endpoints remain available for existing customers. + +.. toctree:: + :maxdepth: 1 + :hidden: + + send-alerts-api + send-changes-api + +Endpoint +-------- + +.. code-block:: + + POST https://api.robusta.dev/webhooks?type=<TYPE>&origin=<ORIGIN>&account_id=<ACCOUNT_ID> + +Query Parameters +---------------- + +.. list-table:: + :widths: 20 70 + :header-rows: 1 + + * - Parameter + - Description + * - ``type`` + - One of ``alert`` or ``change``. ``alert`` is the most common; + ``change`` is used by feature-flag/deployment integrations. + * - ``origin`` + - Identifies the source system (``alertmanager``, ``datadog``, + ``launchdarkly``, ``github``, …). Any non-empty string is accepted — + unknown origins are still stored and parsed by the generic parser. + * - ``account_id`` + - Your Robusta account ID, found in ``generated_values.yaml``. + +Authentication +-------------- + +Send your Robusta API key as a Bearer token. Generate keys in the +Robusta UI under **Settings → API Keys → New API Key**. + +.. code-block:: + + Authorization: Bearer <API_KEY> + +The key must be scoped to the ``account_id`` query parameter. Mismatches +return ``401``. Vendors that cannot send custom HTTP headers may pass the +key as ``&token=<API_KEY>`` instead — the relay accepts either. + +Example: Send an Alert +---------------------- + +.. code-block:: bash + + curl --location --request POST \ + 'https://api.robusta.dev/webhooks?type=alert&origin=datadog&account_id=ACCOUNT_ID' \ + --header 'Authorization: Bearer API_KEY' \ + --header 'Content-Type: application/json' \ + --data-raw '{ "title": "High error rate", "severity": "high" }' + +Example: Send a Change +---------------------- + +.. code-block:: bash + + curl --location --request POST \ + 'https://api.robusta.dev/webhooks?type=change&origin=launchdarkly&account_id=ACCOUNT_ID' \ + --header 'Authorization: Bearer API_KEY' \ + --header 'Content-Type: application/json' \ + --data-raw '{ "name": "beta-checkout", "titleVerb": "updated", "parent": {"name": "production"} }' + +Response +-------- + +A successful request returns ``200`` with the ID of the stored event: + +.. code-block:: json + + { "id": "8f1b...e21" } + +Errors: + +* ``400`` — missing or empty ``account_id``, ``origin``, or ``type``; invalid ``type`` value. +* ``401`` — invalid or out-of-scope API key. +* ``429`` — rate limit exceeded (300 requests per 5-minute window per account). +* ``503`` — transient storage failure; vendors should retry. + +Pick Your Source +---------------- + +.. grid:: 1 1 2 2 + :gutter: 3 + + .. grid-item-card:: :octicon:`pulse;1em;` Send Alerts API + :class-card: sd-bg-light sd-bg-text-light + :link: send-alerts-api + :link-type: doc + + Wire your monitoring system to ``type=alert``. Per-origin + configuration for AlertManager, Datadog, PagerDuty, and 11 others. + + .. grid-item-card:: :octicon:`git-branch;1em;` Send Changes API + :class-card: sd-bg-light sd-bg-text-light + :link: send-changes-api + :link-type: doc + + Wire your feature-flag or deployment system to ``type=change``. + Per-origin configuration for LaunchDarkly, Argo CD, and GitHub. diff --git a/docs/index.rst b/docs/index.rst index 7ecbafbfa..06f0c9f9b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,7 +23,7 @@ Overview <configuration/exporting/robusta-pro-features> Holmes Chat API <configuration/holmesgpt/holmes-chat-api> - configuration/exporting/send-events-api + configuration/webhooks/send-events-api configuration/exporting/alert-export-api configuration/exporting/alert-statistics-api configuration/exporting/rbac-api