inbox_email_analysis.classified

Fires every time an email reported to the Inbox is classified, including reclassifications.

The data payload follows the OCSF Detection Finding (class 2004, v1.4.0) schema so it can be ingested by SIEMs and SOARs without custom mapping.

postWebhookinbox_email_analysis.classified

Headers

webhook-idstring uuid required

Unique identifier of this webhook event. The same id is sent on every retry; use it as an idempotency key.

webhook-timestampinteger required

Example:1780000000

Unix timestamp (seconds) at which this delivery attempt was made. Used together with webhook-id and the body to verify the signature.

webhook-signaturestring required

Example:v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

Space-delimited list of signatures, one per active endpoint secret (e.g. v1,sig1 v1,sig2).

Each signature is v1,<base64(HMAC-SHA256(secret, "<webhook-id>.<webhook-timestamp>.<body>"))>. Verify against the raw request body; re-serializing the JSON will change the bytes and invalidate the signature.

webhook-test'true'

true on a test delivery. A real event never carries this header.

Payload

timestampstring date-time required

ISO 8601 timestamp at which the event was created in Riot. This is the event time, not the delivery attempt time. The delivery time is sent in the webhook-timestamp header.

type'inbox_email_analysis.classified' required

Example payload

{
  "data": {
    "activity_name": "Create",
    "actor": {
      "user": {
        "email_addr": "jane.doe@acme.example",
        "name": "Jane Doe"
      }
    },
    "category_name": "Findings",
    "class_name": "Detection Finding",
    "evidences": [
      {
        "email": {
          "from": "no-reply@suspicious.example",
          "message_uid": "<abc@mail.example>",
          "subject": "Action required"
        }
      }
    ],
    "finding_info": {
      "analytic": {
        "type": "Rule"
      },
      "src_url": "https://hub.tryriot.com/inbox/01HW...",
      "types": [
        "Phishing"
      ]
    },
    "metadata": {
      "product": {
        "feature": {
          "name": "Phishing Reports"
        },
        "name": "Riot",
        "vendor_name": "Riot"
      },
      "version": "1.4.0"
    },
    "observables": [
      {
        "type": "Email Address",
        "type_id": 5,
        "value": "no-reply@suspicious.example"
      }
    ],
    "severity": "High",
    "severity_id": 4,
    "status": "New",
    "type_name": "Detection Finding: Create",
    "unmapped": {
      "riot": {
        "analysis_status": "fraudulent",
        "classification_bucket": "credential_harvesting",
        "explanations": [
          {
            "description": "Sender domain was registered less than 7 days ago.",
            "evidence_key": "auth_checks",
            "evidence_label": "Authentication checks",
            "evidences": [
              "paypa1-secure.example",
              "login-alert.example (in invoice.pdf)"
            ],
            "sentiment": "threat",
            "source": "static_tag"
          }
        ],
        "report_source": "outlook"
      }
    }
  }
}

Response

Event accepted. Any 2xx status code is treated as success; the receiver does not need to return a body.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.