События API

События интеграции, подпись и повторы

События нужны, чтобы не держать частый опрос статуса. RealIQ отправляет событие на ваш URL, когда проверка или цикл мониторинга меняет состояние.

События

check.completed

Проверка завершилась: report_ready, partial или failed.

monitor.cycle_completed

Цикл мониторинга завершён без существенных изменений.

monitor.change_detected

Мониторинг обнаружил изменение относительно прошлого снимка.

monitor.paused

Мониторинг остановлен или не может продолжаться, например из-за баланса.

Состав события проверки

Главные поля для CRM: event, data.check_id, status, risk_score, pdf_url, report_url и доказательный блок.

{
  "event": "check.completed",
  "id": "evt_1780000000_abcd",
  "created_at": "2026-06-28T12:01:18Z",
  "data": {
    "check_id": "b9f6f2f0-b8c1-4f1c-bb8f-3cf3a9dc3b5a",
    "status": "report_ready",
    "type": "full",
    "risk_score": 18,
    "pdf_url": "https://realiq.ru/reports/b9f6f2f0.pdf",
    "report_url": "https://realiq.ru/check-status/b9f6f2f0-b8c1-4f1c-bb8f-3cf3a9dc3b5a",
    "evidence": {
      "check_evidence_root_hash": "9f4a6c...0d71",
      "pdf_sha256": "ab12c4...9f00",
      "datestamp": {
        "value": "2026-06-28T12:01:18Z",
        "provider": "RealIQ"
      },
      "sources": [
        {
          "source_code": "fssp",
          "status": "ok",
          "normalized_result_sha256": "0f4c2b...9a21"
        }
      ]
    }
  }
}

Состав события мониторинга

Для мониторинга важны changed, changes, risk_before/risk_after, act_pdf_url и next_run_at.

{
  "event": "monitor.change_detected",
  "id": "evt_1780600000_monitor",
  "created_at": "2026-07-05T09:00:15Z",
  "data": {
    "monitor_id": 42,
    "run_id": 7,
    "status": "active",
    "type": "full",
    "check_id": "b9f6f2f0-b8c1-4f1c-bb8f-3cf3a9dc3b5a",
    "changed": true,
    "changes": {
      "items": [
        { "text": "Риск-индекс изменился: 12 → 32." }
      ]
    },
    "risk_before": 12,
    "risk_after": 32,
    "act_pdf_url": "https://realiq.ru/reports/monitor-42-run-7.pdf",
    "next_run_at": "2026-07-12T09:00:00Z"
  }
}

HMAC-подпись

Подпись считается по сырому телу запроса: HMAC_SHA256(timestamp + "." + raw_body, webhook_secret). Проверяйте timestamp и сравнивайте подписи сравнением за постоянное время.

Node.js

import crypto from "node:crypto"

function verifyRealiqSignature(rawBody, timestamp, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex")

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  )
}

Python

import hmac
import hashlib

def verify_realiq_signature(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        timestamp.encode("utf-8") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Повторы и защита от дублей

Отвечайте 2xx

Если событие принято, верните HTTP 200/204.

Храните event.id

Не обрабатывайте повторно событие с тем же id.

Не доверяйте только событию

При сомнении перечитайте состояние через GET /checks/{check_id} или GET /monitors/{monitor_id}.