UDI Lens
入口網站English

快速開始

UDI Lens Connect 會把 App 的每一筆掃描，以 HTTPS POST 送到你指定的網址。你只需要準備一個能接收 JSON、並以 API Key 驗證簽章的端點。

你需要

  • 一個公開的 HTTPS 網址（port 443、公開 CA 簽發的有效憑證）
  • 一位訂閱 UDI Lens Connect 的 iPhone 使用者（之後可建立組織，讓同事共用同一個網址）

1. 建立端點

在 App 開啟「設定 → Connect」，輸入你的網址並按「建立」。App 會顯示一次 API Key（whsec_ 開頭），請立即複製並存進你系統的祕密管理（環境變數、Vault、Key Vault 等）。

API Key 只會顯示這一次。遺失時可在 App 或入口網站輪替產生新金鑰。

2. 實作端點

端點收到請求時：

  1. 以原始 body 和 API Key 驗證 webhook-signature（見驗證簽章）
  2. 若 type 為 endpoint.verification，回 200 與 {"challenge": "<data.challenge 原值>"}
  3. 其他事件以 webhook-id 去重、回 2xx，再非同步處理

最小可用的 Node.js 範例：

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

function verify(apiKey, headers, rawBody) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"], sigs = headers["webhook-signature"];
  if (!id || !ts || !sigs || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(apiKey.replace(/^whsec_/, ""), "base64");
  const expected = Buffer.from("v1," + createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64"));
  return sigs.split(" ").some((s) => Buffer.from(s).length === expected.length && timingSafeEqual(Buffer.from(s), expected));
}

Python、C#、Java 範例見驗證簽章。

3. 驗證端點

回到 App 按「驗證」。我們會送出 endpoint.verification，你的端點回傳相同的 challenge 後，端點狀態變為「已啟用」。

4. 送出測試事件

按「送出測試事件」，你會收到一筆 endpoint.test，內容是範例掃描，格式與正式的 scan.created 相同。

5. 開始掃描

開啟 App 的「自動傳送」後，每次掃描完成都會送出 scan.created。離線時 App 會保留，連線恢復後補送。

還沒有端點？

先用線上收件器：它會給你一個臨時網址，你可以把這個網址填進 App，即時看到收到的事件與驗章結果。