ROB-3785 Add Send Events API documentation with integration guides

docs/configuration/exporting/robusta-pro-features.rst

@@ -17,8 +17,7 @@ Data Export and Reporting
 
 * :doc:`Alert Export API <alert-export-api>`: Export historical alert data with filtering by time range, alert name, and account
 * :doc:`Alert Reporting API <alert-statistics-api>`: Get aggregated statistics and counts for different alert types
-* :doc:`Send Alerts API <send-alerts-api>`: Send alerts programmatically from external systems
-* :doc:`Configuration Changes API <configuration-changes-api>`: Track configuration changes in your environment
+* :doc:`Send Events API <send-events-api>`: Send alerts, incidents, and changes from any monitoring source via a single webhook endpoint
 * :doc:`RBAC Configuration API <rbac-api>`: Programmatically manage role-based access control configurations
 
 Getting Started

docs/configuration/exporting/send-events-api.rst

@@ -0,0 +1,191 @@
+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 </configuration/exporting/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=<ORIGIN>&account_id=<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 <API_KEY>
+
+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

docs/configuration/exporting/send-events/alertmanager.rst

@@ -0,0 +1,46 @@
+AlertManager
+=============
+
+Forward Prometheus alerts from AlertManager directly to Robusta.
+
+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=alert&origin=alertmanager&account_id=<ACCOUNT_ID>
+
+Configure AlertManager
+----------------------
+
+Add a webhook receiver to ``alertmanager.yml``:
+
+.. code-block:: yaml
+
+    receivers:
+      - name: robusta
+        webhook_configs:
+          - url: 'https://api.robusta.dev/webhooks?type=alert&origin=alertmanager&account_id=<ACCOUNT_ID>'
+            send_resolved: true
+            http_config:
+              authorization:
+                type: Bearer
+                credentials: <ROBUSTA_API_KEY>
+
+    route:
+      receiver: robusta
+      continue: true
+
+Set ``continue: true`` if Robusta is not your only receiver, so alerts also reach your other destinations.
+
+Verify
+------
+
+Open **Settings → Delivery Log** in the Robusta UI to see the request arrive, then check the timeline for the parsed alert.

docs/configuration/exporting/send-events/aws-cloudwatch.rst

@@ -0,0 +1,64 @@
+AWS CloudWatch
+===============
+
+Forward CloudWatch alarms to Robusta. CloudWatch cannot POST to arbitrary HTTPS endpoints directly, so the recipe is **CloudWatch → SNS → Lambda → Robusta**.
+
+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.
+* AWS account permissions to create Lambda functions and SNS topics.
+
+Webhook URL
+-----------
+
+.. code-block::
+
+    https://api.robusta.dev/webhooks?type=alert&origin=awscloudwatch&account_id=<ACCOUNT_ID>
+
+Recipe
+------
+
+1. Create an SNS topic named ``robusta``. Add it as a notification action on the CloudWatch alarms you want forwarded.
+2. Create a Lambda function (Python 3.12) and subscribe it to the ``robusta`` SNS topic. Store the Robusta API key in **Lambda → Configuration → Environment variables** as ``ROBUSTA_API_KEY``.
+3. Use the following handler:
+
+   .. code-block:: python
+
+       import json
+       import os
+       import urllib.error
+       import urllib.request
+
+       URL = "https://api.robusta.dev/webhooks?type=alert&origin=awscloudwatch&account_id=<ACCOUNT_ID>"
+       TIMEOUT_SECONDS = 5
+
+       def lambda_handler(event, context):
+           for record in event["Records"]:
+               body = record["Sns"]["Message"]
+               req = urllib.request.Request(
+                   URL,
+                   data=body.encode("utf-8"),
+                   method="POST",
+                   headers={
+                       "Content-Type": "application/json",
+                       "Authorization": f"Bearer {os.environ['ROBUSTA_API_KEY']}",
+                   },
+               )
+               try:
+                   urllib.request.urlopen(req, timeout=TIMEOUT_SECONDS).read()
+               except urllib.error.URLError as exc:
+                   print(f"failed to forward CloudWatch alarm to Robusta: {exc}")
+                   raise
+           return {"ok": True}
+
+4. Replace ``<ACCOUNT_ID>`` with your Robusta account ID and deploy.
+
+Alternatively, if you already use **Amazon EventBridge → API destination**, point the destination at the same URL with a Bearer token connection — no Lambda required.
+
+Verify
+------
+
+Use the **Test alarm** action in CloudWatch. The event should appear in **Settings → Delivery Log** and on the Robusta timeline.

docs/configuration/exporting/send-events/azure-monitor.rst

@@ -0,0 +1,38 @@
+Azure Monitor
+==============
+
+Forward Azure Monitor alerts to Robusta via an Action Group webhook receiver.
+
+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.
+* Azure ``Contributor`` access to the resource group hosting the Action Group.
+
+Webhook URL
+-----------
+
+.. code-block::
+
+    https://api.robusta.dev/webhooks?type=alert&origin=azure&account_id=<ACCOUNT_ID>
+
+Configure Azure
+---------------
+
+Action Group webhook receivers do not allow custom headers, so authenticate via the URL:
+
+.. code-block::
+
+    https://api.robusta.dev/webhooks?type=alert&origin=azure&account_id=<ACCOUNT_ID>&token=<ROBUSTA_API_KEY>
+
+1. In the Azure Portal, open **Monitor → Action groups** and either create a new group or edit an existing one.
+2. Under **Actions**, add an action of type **Webhook**.
+3. Name it ``Robusta`` and set the **URI** to the URL above. Leave **Enable the common alert schema** on.
+4. Save the action group and attach it to the alert rules you want to forward.
+
+Verify
+------
+
+Use the action group's **Test** option. The event should appear in **Settings → Delivery Log** and on the Robusta timeline.

docs/configuration/exporting/send-events/datadog.rst

@@ -0,0 +1,38 @@
+Datadog
+========
+
+Forward Datadog monitor alerts to Robusta via a Datadog webhook integration.
+
+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.
+* A Datadog admin able to create webhook integrations.
+
+Webhook URL
+-----------
+
+.. code-block::
+
+    https://api.robusta.dev/webhooks?type=alert&origin=datadog&account_id=<ACCOUNT_ID>
+
+Configure Datadog
+-----------------
+
+1. In Datadog, go to **Integrations → Webhooks → New** and name the webhook ``robusta``.
+2. Set the URL to the webhook URL above.
+3. Under **Custom Headers**, add:
+
+   .. code-block:: json
+
+       { "Authorization": "Bearer <ROBUSTA_API_KEY>" }
+
+4. Leave the default payload.
+5. Save. In any monitor, set the **Notify** field to ``@webhook-robusta`` to forward its alerts to Robusta.
+
+Verify
+------
+
+Trigger a test alert from a Datadog monitor. The event should appear in **Settings → Delivery Log** and on the Robusta timeline.