開発者 API と Webhook

クイックスタート

アプリの Wire → API キーでキーを作成し、どこからでも API を呼び出せます。レスポンスは JSON、時刻は ISO-8601 UTC です。

curl

curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/alerts?limit=5

Node.js

const res = await fetch('https://realityradar-7h6.pages.dev/api/v1/public/entities', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.RADAR_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ entityType: 'software_version', displayName: 'Node.js', modelOrVersion: '18.20.0',
    identifiers: { eolProduct: 'nodejs' }, relationship: 'used' }),
});
console.log(res.status, await res.json());

Python

import os, requests
r = requests.get("https://realityradar-7h6.pages.dev/api/v1/public/events", params={"type": "product_recall", "limit": 20},
                 headers={"Authorization": f"Bearer {os.environ['RADAR_KEY']}"}, timeout=10)
r.raise_for_status()
for e in r.json()["items"]:
    print(e["firstSeenAt"], e["title"], e["sourceUrl"])

認証

キーを Bearer トークンとして送ります。キーは一度だけ表示されハッシュのみ保存されます。30・90・365日で期限切れにでき、24時間の重複期間を設けて切り替えられます。

HTTP

Authorization: Bearer rr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

スコープ

キーには選んだスコープだけが付きます。範囲外のリクエストは 403 insufficient_scope になるため、読み取り専用のキーでアイテム追加や Webhook 管理はできません。

スコープ	エンドポイント
`read:signals`	`GET /public/events` `GET /public/events/{id}`
`read:entities`	`GET /public/entities`
`write:entities`	`POST /public/entities`
`read:alerts`	`GET /public/alerts`
`manage:webhooks`	`GET /public/webhooks` `POST /public/webhooks` `DELETE /public/webhooks/{id}` `GET /public/webhooks/{id}/deliveries` `POST /public/webhooks/{id}/deliveries/{deliveryId}/replay`

レート制限

標準キーは毎分60回、高い上限のキーは毎分300回です。429 が返ったら待って再試行してください。キー別・エンドポイント別の使用量は Wire で確認できます。

ページング

一覧エンドポイントは items と nextCursor を返します。null になるまで cursor を渡してください。カーソルは不透明で、ページング中は安定しています。

Python

cursor = None
while True:
    page = requests.get(f"https://realityradar-7h6.pages.dev/api/v1/public/events", headers=H, params={"limit": 100, "cursor": cursor}).json()
    handle(page["items"])
    cursor = page["nextCursor"]
    if not cursor:
        break

エラー

エラーは共通の形式と固定のコードで返ります。5xx と 429 は間隔を空けて再試行し、4xx はリクエストを見直してください。

JSON

{ "error": { "code": "insufficient_scope", "message": "This key lacks the \"write:entities\" scope" } }

`invalid_api_key`	401	キーがない、形式が不正、または失効
`api_key_expired`	401	有効期限または切り替え猶予を過ぎた
`insufficient_scope`	403	このエンドポイントに必要なスコープがない
`not_found`	404	存在しない、またはこのワークスペースから見えない
`plan_limit`	409	無料プランのアイテム上限に達した
`ssrf_blocked`	422	URL がプライベートまたは内部アドレスを指している
`rate_limited`	429	リクエストが多すぎます — 時間をおいて再試行

Webhook

設定したレベル以上のアラートが作成されると JSON イベントを POST します。配信履歴はステータスと遅延とともに30日間保存され、ワンクリックで再送できます。

HTTP

POST /your/endpoint
Content-Type: application/json
User-Agent: RealityRadar-Webhook/1.0
X-Radar-Signature: t=1761112800,v1=5f2b…a91c,v1=03de…77b0

{"type":"alert.created","alert":{"impactLevel":"critical","matchType":"exact",…},"event":{…}}

署名の検証

t、ドット、生の本文をシークレットで HMAC-SHA256 し、いずれかの v1 と定数時間で比較し、5分より古い時刻は拒否します。シークレット更新後の24時間は v1 が2つ届きます。

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the exact bytes you received (do not re-serialize JSON)
export function verifyRadar(header, rawBody, secret) {
  const parts = header.split(',').map((p) => p.split('='));
  const t = Number(parts.find(([k]) => k === 't')?.[1]);
  const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const mac = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return sigs.some((v) => v.length === mac.length && timingSafeEqual(Buffer.from(v), Buffer.from(mac)));
}

Python

import hmac, hashlib, time

def verify_radar(header: str, raw_body: bytes, secret: str) -> bool:
    parts = [p.split("=", 1) for p in header.split(",")]
    t = next((int(v) for k, v in parts if k == "t"), None)
    sigs = [v for k, v in parts if k == "v1"]
    if t is None or abs(time.time() - t) > 300:
        return False
    mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(mac, s) for s in sigs)

func VerifyRadar(header string, rawBody []byte, secret string) bool {
	var t int64 = -1
	var sigs []string
	for _, p := range strings.Split(header, ",") {
		k, v, ok := strings.Cut(p, "=")
		if !ok { continue }
		if k == "t" { t, _ = strconv.ParseInt(v, 10, 64) }
		if k == "v1" { sigs = append(sigs, v) }
	}
	if t < 0 || math.Abs(float64(time.Now().Unix()-t)) > 300 { return false }
	m := hmac.New(sha256.New, []byte(secret))
	fmt.Fprintf(m, "%d.", t)
	m.Write(rawBody)
	want := hex.EncodeToString(m.Sum(nil))
	for _, s := range sigs {
		if hmac.Equal([]byte(want), []byte(s)) { return true }
	}
	return false
}

curl

# Replay a delivery (fresh timestamp + signature)
curl -X POST -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/replay

依存関係と OSV

pkg:npm/lodash のような purl と正確なバージョンでパッケージを追跡します。OSV.dev を確認し、バージョンが影響リストにあれば完全一致とします。ロックファイルや SBOM はアプリの取り込みからアップロードできます。

curl

curl -X POST -H "Authorization: Bearer rr_live_…" -H "Content-Type: application/json" \
  -d '{"entityType":"software_version","displayName":"lodash","modelOrVersion":"4.17.20","identifiers":{"purl":"pkg:npm/lodash"},"relationship":"used"}' \
  https://realityradar-7h6.pages.dev/api/v1/public/entities

用語集

レスポンスに出てくる用語です。

Signal（シグナル）: 公式の出典で見つかった変化。根拠と時刻が付きます。
Beacon（ビーコン）: データの出典。A は公式の規制機関・メーカー、B は精査されたデータベースです。
一致タイプ: exact・strong・probable・weak — イベントが自分のアイテムに関するものだとどれだけ確かか。確定として表現するのは exact と strong だけです。
関連度・信頼度・深刻度: 別々に計算する0〜100のスコア3つ：自分に関係あるか、根拠はどれだけ信頼できるか、変化はどれだけ深刻か。
purl: pkg:npm/lodash のようなパッケージ URL。OSV の照合に使う標準の識別子です。
証拠台帳: 保存したすべての根拠のハッシュチェーン。誰でも改ざんの有無を検証できます。

Reality Radar で構築する

クイックスタート

認証

スコープ

レート制限

ページング

エラー

Webhook

署名の検証

依存関係と OSV

用語集