WEBHOOKS

Webhooks

You do not poll for new recordings. When one finishes processing, we POST a signed event to the URL you registered, and you pull the text with the capability token. The main event is recording.ready; card and processing events are listed under All events.

不需要輪詢新錄音。一條錄音處理完成後，我們會向你登記的地址 POST 一個帶簽名的事件，你再用能力令牌去取正文。 最主要的事件是 recording.ready；卡片與處理事件見全部事件。

recording.ready

{
  "event": "recording.ready",
  "recordingId": "rec_01J9…",
  "title": "Thursday standup",
  "userId": "7f3c…",
  "ownerVerified": true,
  "svVerdict": "owner",
  "timestamp": 1761801600
}

When it fires

All of these have to hold. Any one of them failing means no delivery, silently:

以下條件必須同時成立。任一不成立即不投遞，且不報錯：

• The recording's visibility is visible. Hidden and rejected recordings are never pushed — this is a privacy gate, not a filter you can opt out of.
• That user has a live, un-revoked grant to your app that includes recordings.read.
• Your app is not banned.
• Your app has a webhook URL configured.
• If your app is still sandbox, the recording belongs to your own account. Sandbox apps never receive other people's recordings.

• 該錄音的 visibility 為 visible。隱藏與被拒的錄音永不推送——這是隱私閘門，不是可以關掉的過濾器。
• 該用戶對你的應用有未撤銷的有效授權，且包含 recordings.read。
• 你的應用不處於 banned 狀態。
• 你的應用已配置 webhook 地址。
• 若應用仍是 sandbox 態，該錄音屬於你自己的帳號。sandbox 應用永遠收不到他人的錄音。

Verify the signature

X-Vyslo-Signature is the lowercase hex HMAC-SHA256 of the raw request body keyed with your app's webhookSecret. Verify before you parse, and compare in constant time. Re-serializing the JSON first will not produce the same digest.

X-Vyslo-Signature 是用應用的 webhookSecret 對原始請求體 做 HMAC-SHA256 後的小寫 hex。先校驗再解析，並用恆定時間比較。先把 JSON 重新序列化會算出不同的摘要。

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["VYSLO_WEBHOOK_SECRET"].encode()

@app.post("/hooks/vyslo")
def vyslo_hook():
    raw = request.get_data()                      # bytes, exactly as received
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Vyslo-Signature", "")):
        abort(401)

    event = request.get_json()
    enqueue(event["recordingId"])                 # idempotent by recordingId
    return "", 204                               # ack first, work after

val ok = VysloOpen.verifyWebhookSignature(
    webhookSecret = secret,
    rawBody = body,
    signature = header("X-Vyslo-Signature"),
)

Delivery and retries

What your endpoint should do

• Answer fast, work later. Ten seconds is the budget for the whole attempt, so acknowledge and queue rather than transcribing inline.
• Be idempotent on recordingId. A slow 2xx that we timed out on is still a successful run on your side — you will see that id again.
• Verify, then trust. An unverified body is an unauthenticated POST from the open internet.
• Serve HTTPS. http:// is accepted by the API for local development, but the payload names your users.

• 先應答，後處理。單次嘗試總預算 10 秒，請先 ack 入隊，不要在請求裡同步幹活。
• 按 recordingId 幂等。我們這邊超時的那次慢 2xx，在你那邊仍是一次成功執行——同一個 id 會再來一次。
• 先校驗，再信任。未校驗的請求體，等於來自公網的未鑑權 POST。
• 用 HTTPS。API 允許 http:// 供本機開發，但載荷裡有你用戶的信息。

All events

Every event uses the same envelope, signature and retry schedule as recording.ready, with deviceId added for card events. No payload carries transcript text. Card events reach the cloud through the phone the card is connected to; over BLE your app receives them directly.

所有事件與 recording.ready 使用同樣的信封、簽名與重試節奏，卡片事件另帶 deviceId。 任何載荷都不含轉寫正文。卡片事件經卡片所連的手機送到雲端；經 BLE 時，你的 App 直接收到。