Tighten Send Events API docs: customer-facing wording and param order

claude · claude · commit f398591ebf6d · 2026-05-12T10:40:58.000Z
- Replace 'accepts any JSON payload' with 'accepts the default
  payload structure of the supported origins'.
- Remove paragraph describing internal storage/parsing behavior.
- Replace the 'Unsupported sources' section with a brief 'Other
  sources' note that does not mention parsers.
- Drop incidental references to internal terminology in per-origin
  pages (per-origin/generic parser, the relay, dedup-key preservation).
- Reorder all webhook URL examples to type, origin, account_id.
diff --git a/docs/configuration/exporting/send-events-api.rst b/docs/configuration/exporting/send-events-api.rst
@@ -32,13 +32,11 @@ This is the recommended ingestion path for new integrations. The legacy :doc:`Se
 Overview
 --------
 
-The endpoint accepts any JSON payload. The request is parameterized by query string:
+The endpoint accepts the default payload structure of the supported origins. The request is parameterized by query string:
 
 .. code-block::
 
-    POST https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=<ORIGIN>&type=<TYPE>
-
-Robusta stores every payload verbatim, then asynchronously parses it into the Robusta UI timeline. If a per-origin parser is registered for ``origin``, it is used; otherwise a generic JSON parser handles the payload. Parse failures are visible in the **Delivery Log** UI page so you can self-debug.
+    POST https://api.robusta.dev/webhooks?type=<TYPE>&origin=<ORIGIN>&account_id=<ACCOUNT_ID>
 
 Query Parameters
 ----------------
@@ -51,17 +49,17 @@ Query Parameters
      - Type
      - Description
      - Required
-   * - ``account_id``
+   * - ``type``
      - string
-     - Your Robusta account ID, found in ``generated_values.yaml``.
+     - One of ``alert``, ``incident``, or ``change``.
      - Yes
    * - ``origin``
      - string
-     - Identifies the monitoring product (for example ``alertmanager``, ``pagerduty``, ``datadog``). Free-form; selects the per-origin parser when one exists.
+     - Identifies the monitoring product (for example ``alertmanager``, ``pagerduty``, ``datadog``).
      - Yes
-   * - ``type``
+   * - ``account_id``
      - string
-     - One of ``alert``, ``incident``, or ``change``.
+     - Your Robusta account ID, found in ``generated_values.yaml``.
      - Yes
 
 Authentication
@@ -81,7 +79,7 @@ Example Request
 .. code-block:: bash
 
     curl --location --request POST \
-      'https://api.robusta.dev/webhooks?account_id=ACCOUNT_ID&origin=datadog&type=alert' \
+      '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" }'
@@ -238,12 +236,7 @@ Other
         :link: send-events/solarwinds
         :link-type: doc
 
-Unsupported sources
--------------------
-
-Any monitoring system that can POST JSON to a URL works. Pick a free-form ``origin`` value, paste the URL into the vendor's webhook configuration, and Robusta's generic parser will handle the payload. The AI investigator reads the raw payload along with the structured event, so source-specific fields are preserved even without a dedicated parser.
-
-Delivery Log
-------------
+Other sources
+-------------
 
-Every received payload — parsed, pending, or failed — is visible in the Robusta UI under **Settings → Delivery Log**, scoped to your account and sorted by recency. Use it to confirm that a vendor is reaching Robusta, view the original request body, and inspect parser errors.
+Any monitoring system that can POST JSON to a URL is supported. Choose a value for ``origin`` that identifies your source, then paste the URL into your vendor's webhook configuration.
diff --git a/docs/configuration/exporting/send-events/alertmanager.rst b/docs/configuration/exporting/send-events/alertmanager.rst
@@ -1,7 +1,7 @@
 AlertManager
 =============
 
-Forward Prometheus alerts from AlertManager directly to Robusta. Robusta's per-origin parser maps AlertManager labels and annotations onto the timeline; the original payload is preserved for HolmesGPT.
+Forward Prometheus alerts from AlertManager directly to Robusta.
 
 Prerequisites
 -------------
@@ -15,7 +15,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=alertmanager&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=alertmanager&account_id=<ACCOUNT_ID>
 
 Configure AlertManager
 ----------------------
@@ -27,7 +27,7 @@ Add a webhook receiver to ``alertmanager.yml``:
     receivers:
       - name: robusta
         webhook_configs:
-          - url: 'https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=alertmanager&type=alert'
+          - url: 'https://api.robusta.dev/webhooks?type=alert&origin=alertmanager&account_id=<ACCOUNT_ID>'
             send_resolved: true
             http_config:
               authorization:
diff --git a/docs/configuration/exporting/send-events/argocd.rst b/docs/configuration/exporting/send-events/argocd.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=argocd&type=change
+    https://api.robusta.dev/webhooks?type=change&origin=argocd&account_id=<ACCOUNT_ID>
 
 Configure Argo CD Notifications
 --------------------------------
@@ -26,7 +26,7 @@ Add a webhook service and a template to ``argocd-notifications-cm``:
 .. code-block:: yaml
 
     service.webhook.robusta: |
-      url: https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=argocd&type=change
+      url: https://api.robusta.dev/webhooks?type=change&origin=argocd&account_id=<ACCOUNT_ID>
       headers:
         - name: Authorization
           value: Bearer <ROBUSTA_API_KEY>
diff --git a/docs/configuration/exporting/send-events/aws-cloudwatch.rst b/docs/configuration/exporting/send-events/aws-cloudwatch.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=awscloudwatch&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=awscloudwatch&account_id=<ACCOUNT_ID>
 
 Recipe
 ------
@@ -32,7 +32,7 @@ Recipe
        import urllib.error
        import urllib.request
 
-       URL = "https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=awscloudwatch&type=alert"
+       URL = "https://api.robusta.dev/webhooks?type=alert&origin=awscloudwatch&account_id=<ACCOUNT_ID>"
        TIMEOUT_SECONDS = 5
 
        def lambda_handler(event, context):
diff --git a/docs/configuration/exporting/send-events/azure-monitor.rst b/docs/configuration/exporting/send-events/azure-monitor.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=azure&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=azure&account_id=<ACCOUNT_ID>
 
 Configure Azure
 ---------------
@@ -25,11 +25,11 @@ Action Group webhook receivers do not allow custom headers, so authenticate via
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=azure&type=alert&token=<ROBUSTA_API_KEY>
+    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 — Robusta's parser is built against it.
+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
diff --git a/docs/configuration/exporting/send-events/datadog.rst b/docs/configuration/exporting/send-events/datadog.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=datadog&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=datadog&account_id=<ACCOUNT_ID>
 
 Configure Datadog
 -----------------
@@ -29,7 +29,7 @@ Configure Datadog
 
        { "Authorization": "Bearer <ROBUSTA_API_KEY>" }
 
-4. Leave the default payload, or customize it. Robusta's per-origin parser handles the standard Datadog payload shape.
+4. Leave the default payload.
 5. Save. In any monitor, set the **Notify** field to ``@webhook-robusta`` to forward its alerts to Robusta.
 
 Verify
diff --git a/docs/configuration/exporting/send-events/dynatrace.rst b/docs/configuration/exporting/send-events/dynatrace.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=dynatrace&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=dynatrace&account_id=<ACCOUNT_ID>
 
 Configure Dynatrace
 -------------------
@@ -29,7 +29,7 @@ Configure Dynatrace
 
        Authorization: Bearer <ROBUSTA_API_KEY>
 
-4. Use the default JSON payload template, or customize it. Robusta's generic parser handles arbitrary fields.
+4. Use the default JSON payload template.
 5. Save and assign the integration to your alerting profile.
 
 Verify
diff --git a/docs/configuration/exporting/send-events/gcp-monitoring.rst b/docs/configuration/exporting/send-events/gcp-monitoring.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=gcp&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=gcp&account_id=<ACCOUNT_ID>
 
 Configure GCP
 -------------
@@ -25,9 +25,9 @@ GCP webhook notification channels do not support custom headers in the console,
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=gcp&type=alert&token=<ROBUSTA_API_KEY>
+    https://api.robusta.dev/webhooks?type=alert&origin=gcp&account_id=<ACCOUNT_ID>&token=<ROBUSTA_API_KEY>
 
-The relay accepts ``token`` as an alternate to the ``Authorization`` header.
+The ``token`` query parameter is accepted as an alternative to the ``Authorization`` header.
 
 1. In the GCP Console, go to **Monitoring → Alerting → Edit Notification Channels**.
 2. Click **Add new** under **Webhooks**.
diff --git a/docs/configuration/exporting/send-events/github.rst b/docs/configuration/exporting/send-events/github.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=github&type=change
+    https://api.robusta.dev/webhooks?type=change&origin=github&account_id=<ACCOUNT_ID>
 
 Configure GitHub
 ----------------
@@ -28,7 +28,7 @@ Configure GitHub
 
    .. code-block::
 
-       https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=github&type=change&token=<ROBUSTA_API_KEY>
+       https://api.robusta.dev/webhooks?type=change&origin=github&account_id=<ACCOUNT_ID>&token=<ROBUSTA_API_KEY>
 
    .. warning::
 
diff --git a/docs/configuration/exporting/send-events/grafana.rst b/docs/configuration/exporting/send-events/grafana.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=grafana&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=grafana&account_id=<ACCOUNT_ID>
 
 Configure Grafana
 -----------------
diff --git a/docs/configuration/exporting/send-events/incidentio.rst b/docs/configuration/exporting/send-events/incidentio.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=incidentio&type=incident
+    https://api.robusta.dev/webhooks?type=incident&origin=incidentio&account_id=<ACCOUNT_ID>
 
 Configure Incident.io
 ---------------------
diff --git a/docs/configuration/exporting/send-events/launchdarkly.rst b/docs/configuration/exporting/send-events/launchdarkly.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=launchdarkly&type=change
+    https://api.robusta.dev/webhooks?type=change&origin=launchdarkly&account_id=<ACCOUNT_ID>
 
 Configure LaunchDarkly
 ----------------------
diff --git a/docs/configuration/exporting/send-events/nagios.rst b/docs/configuration/exporting/send-events/nagios.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=nagios&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=nagios&account_id=<ACCOUNT_ID>
 
 Configure Nagios
 ----------------
@@ -53,7 +53,7 @@ Then reference ``$USER20$`` from the notification command:
                 "type": "$NOTIFICATIONTYPE$",
                 "output": "$SERVICEOUTPUT$"
             }' \
-            'https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=nagios&type=alert'
+            'https://api.robusta.dev/webhooks?type=alert&origin=nagios&account_id=<ACCOUNT_ID>'
     }
 
 Define an analogous ``notify-robusta-host`` command, then attach both to a Nagios contact:
diff --git a/docs/configuration/exporting/send-events/newrelic.rst b/docs/configuration/exporting/send-events/newrelic.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=newrelic&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=newrelic&account_id=<ACCOUNT_ID>
 
 Configure New Relic
 -------------------
@@ -29,7 +29,7 @@ Configure New Relic
 
        Authorization: Bearer <ROBUSTA_API_KEY>
 
-4. Use the default payload template. Robusta preserves the original ``aggregationKeys`` field as the dedup key.
+4. Use the default payload template.
 5. Create a **Workflow** that routes the desired policy to this destination.
 
 Verify
diff --git a/docs/configuration/exporting/send-events/opsgenie.rst b/docs/configuration/exporting/send-events/opsgenie.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=opsgenie&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=opsgenie&account_id=<ACCOUNT_ID>
 
 Configure Opsgenie
 ------------------
diff --git a/docs/configuration/exporting/send-events/pagerduty.rst b/docs/configuration/exporting/send-events/pagerduty.rst
@@ -18,13 +18,13 @@ For incidents:
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=pagerduty&type=incident
+    https://api.robusta.dev/webhooks?type=incident&origin=pagerduty&account_id=<ACCOUNT_ID>
 
 For AIOps-forwarded alerts:
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=pagerduty&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=pagerduty&account_id=<ACCOUNT_ID>
 
 Configure PagerDuty
 -------------------
diff --git a/docs/configuration/exporting/send-events/rootly.rst b/docs/configuration/exporting/send-events/rootly.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=rootly&type=incident
+    https://api.robusta.dev/webhooks?type=incident&origin=rootly&account_id=<ACCOUNT_ID>
 
 Configure Rootly
 ----------------
diff --git a/docs/configuration/exporting/send-events/sentry.rst b/docs/configuration/exporting/send-events/sentry.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=sentry&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=sentry&account_id=<ACCOUNT_ID>
 
 Configure Sentry
 ----------------
diff --git a/docs/configuration/exporting/send-events/solarwinds.rst b/docs/configuration/exporting/send-events/solarwinds.rst
@@ -16,7 +16,7 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=solarwinds&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=solarwinds&account_id=<ACCOUNT_ID>
 
 Configure SolarWinds
 --------------------
@@ -29,7 +29,7 @@ SolarWinds does not ship a native bearer-token webhook action. Use the **Execute
       -H "Authorization: Bearer <ROBUSTA_API_KEY>" ^
       -H "Content-Type: application/json" ^
       --data "{ \"alertName\": \"${N=Alerting;M=AlertName}\", \"node\": \"${N=SwisEntity;M=Caption}\", \"severity\": \"${N=Alerting;M=Severity}\", \"message\": \"${N=Alerting;M=AlertMessage}\" }" ^
-      "https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=solarwinds&type=alert"
+      "https://api.robusta.dev/webhooks?type=alert&origin=solarwinds&account_id=<ACCOUNT_ID>"
 
 Save the action and attach it to the alerts you want forwarded.
 
diff --git a/docs/configuration/exporting/send-events/splunk.rst b/docs/configuration/exporting/send-events/splunk.rst
@@ -16,13 +16,13 @@ Webhook URL
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=splunk&type=alert
+    https://api.robusta.dev/webhooks?type=alert&origin=splunk&account_id=<ACCOUNT_ID>
 
 Splunk's built-in **Webhook** alert action does not support custom headers. Authenticate via the URL:
 
 .. code-block::
 
-    https://api.robusta.dev/webhooks?account_id=<ACCOUNT_ID>&origin=splunk&type=alert&token=<ROBUSTA_API_KEY>
+    https://api.robusta.dev/webhooks?type=alert&origin=splunk&account_id=<ACCOUNT_ID>&token=<ROBUSTA_API_KEY>
 
 Configure Splunk
 ----------------
