{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/zh-TW/develop/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhook","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook","__idx":0},"children":["Webhook"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook 讓您的應用程式在 AI 任務完成時，收到狀態為 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," 或 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," 的非同步通知。通知會送至您控管的 HTTP 端點，並遵循 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md"},"children":["Standard Webhooks Specification"]},"。"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"webhook-secret","__idx":1},"children":["Webhook Secret"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"webhook-secret-的結構","__idx":2},"children":["Webhook Secret 的結構"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["我們使用 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC-SHA256"]}," 簽章機制的 webhook secret，webhook secret 以 base64 編碼，並加上 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whsec_"]}," 前綴以便辨識。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["webhook secret 範例："]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whsec_NDQzMzYxNzkzMzE0NjYyNDM6OTIxOTcwNDIxODQ"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"使用-standard-webhooks-套件實作-webhook","__idx":3},"children":["使用 Standard Webhooks 套件實作 Webhook"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["我們強烈建議使用 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Standard Webhooks Library"]}," 的官方實作，您不必擔心簽章驗證的細節。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["使用官方實作也能確保簽章驗證安全且正確。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations"},"children":["https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"自行實作-webhook","__idx":4},"children":["自行實作 Webhook"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["請仔細理解 webhook secret 的結構，參考 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#signature-scheme"},"children":["Signature scheme"]}," 中的對稱（Symmetric）部分。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["當您準備為簽章輸入內容簽章時，請移除 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whsec_"]}," 前綴，並將剩下的字串做 base64 解碼，取得 secret 的實際位元組，用來進行 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC-SHA256"]}," 雜湊。"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"webhook-請求範例","__idx":5},"children":["Webhook 請求範例"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST https://yourdomain.com/webhook-endpoint\nContent-Type: application/json\nwebhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848\nwebhook-timestamp: 1761112900\nwebhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"created_at\": 1761112848,\n  \"data\": {\n    \"task_id\": \"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4\",\n    \"task_status\": \"success\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"http-標頭","__idx":6},"children":["HTTP 標頭"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"webhook-id","__idx":7},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-id"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["webhook 遞送的唯一識別碼。"," ","此值在重試之間保持一致，應用於冪等性（idempotency）處理。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"webhook-timestamp","__idx":8},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-timestamp"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["webhook 送出時的 Unix epoch 時間戳（秒）。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"webhook-signature","__idx":9},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["'v1' 後接逗號（,），再接 base64 編碼的 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC-SHA256"]}," 簽章。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["'v1' 表示簽章機制的版本，目前是唯一支援的版本。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["base64 編碼的 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC-SHA256"]}," 簽章，是使用您的 webhook secret 對簽章輸入內容簽章後的結果。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["簽章輸入格式："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["已簽章內容範例："]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{\"created_at\":1761112848,\"data\":{\"task_id\":\"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4\",\"task_status\":\"success\"}}\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"請求內容","__idx":10},"children":["請求內容"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"created_at","__idx":11},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unix epoch 時間戳（秒），表示任務完成的時間。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"data","__idx":12},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["包含事件內容（event payload）。"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"欄位"},"children":["欄位"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"說明"},"children":["說明"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["task_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["建立任務時回傳的任務識別碼。請使用此 ID 查詢最終任務結果。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["task_status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["任務完成狀態。可能值為：",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},"、",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},"。"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"整合指南","__idx":13},"children":["整合指南"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhook-整合指南","__idx":14},"children":["Webhook 整合指南"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["在您的伺服器上準備一個 webhook 端點。"]}," ","確認該端點可接受 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," 請求，且可透過 HTTPS 存取。"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["在 API Console 中建立 webhook。"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["執行 AI 任務並記錄 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["task_id"]},"。"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["處理 webhook 通知，使用 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["task_id"]}," 取得任務結果。"]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"建立-webhook-端點","__idx":15},"children":["建立 Webhook 端點"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["前往 API Console 的 Webhook 管理頁面："]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://yce.makeupar.com/api-console/en/webhook/"},"children":["https://yce.makeupar.com/api-console/en/webhook/"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"1-找到-webhook-區塊","__idx":16},"children":["1. 找到 Webhook 區塊"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_main_bae171663b.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"2-建立新的-webhook-端點","__idx":17},"children":["2. 建立新的 Webhook 端點"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_create_cd28e68fa3.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["您最多可同時設定 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["10 個 webhook 端點"]},"。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"3-保護您的-webhook-secret","__idx":18},"children":["3. 保護您的 Webhook Secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["您的 webhook secret 用於驗證 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]},"。"," ","請妥善保管，切勿公開揭露。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_secret_key_6fe757a7de.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"4-管理既有-webhooks","__idx":19},"children":["4. 管理既有 Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_manage_endpoints_3bed715de9.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"驗證簽章","__idx":20},"children":["驗證簽章"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"在您的伺服器上處理-webhook-請求","__idx":21},"children":["在您的伺服器上處理 Webhook 請求"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["我們建議使用 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Standard Webhooks Library"]}," 的官方實作："]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations"},"children":["https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["這能確保簽章驗證安全且正確。"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["您也可以使用 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Standard Webhooks Simulator"]}," 測試或除錯內容："]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.standardwebhooks.com/simulate"},"children":["https://www.standardwebhooks.com/simulate"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"驗證-webhook-簽章","__idx":22},"children":["驗證 Webhook 簽章"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["請參考 webhook 請求範例："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST https://yourdomain.com/webhook-endpoint\nContent-Type: application/json\nwebhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848\nwebhook-timestamp: 1761112900\nwebhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["請求內容："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"created_at\": 1761112848,\n  \"data\": {\n    \"task_id\": \"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4\",\n    \"task_status\": \"success\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["簽章輸入格式將為："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["已簽章內容範例："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{\"created_at\":1761112848,\"data\":{\"task_id\":\"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4\",\"task_status\":\"success\"}}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["使用您的 webhook secret 金鑰，將以 HMAC-SHA256 加密的已簽章內容，與收到的 webhook-signature 進行驗證。"," ","範例："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=\n"},"children":[]}]},"headings":[{"value":"Webhook","id":"webhook","depth":1},{"value":"Webhook Secret","id":"webhook-secret","depth":4},{"value":"Webhook Secret 的結構","id":"webhook-secret-的結構","depth":5},{"value":"使用 Standard Webhooks 套件實作 Webhook","id":"使用-standard-webhooks-套件實作-webhook","depth":5},{"value":"自行實作 Webhook","id":"自行實作-webhook","depth":5},{"value":"Webhook 請求範例","id":"webhook-請求範例","depth":4},{"value":"HTTP 標頭","id":"http-標頭","depth":4},{"value":"webhook-id","id":"webhook-id","depth":5},{"value":"webhook-timestamp","id":"webhook-timestamp","depth":5},{"value":"webhook-signature","id":"webhook-signature","depth":5},{"value":"請求內容","id":"請求內容","depth":4},{"value":"created_at","id":"created_at","depth":5},{"value":"data","id":"data","depth":5},{"value":"整合指南","id":"整合指南","depth":2},{"value":"Webhook 整合指南","id":"webhook-整合指南","depth":3},{"value":"建立 Webhook 端點","id":"建立-webhook-端點","depth":4},{"value":"1. 找到 Webhook 區塊","id":"1-找到-webhook-區塊","depth":5},{"value":"2. 建立新的 Webhook 端點","id":"2-建立新的-webhook-端點","depth":5},{"value":"3. 保護您的 Webhook Secret","id":"3-保護您的-webhook-secret","depth":5},{"value":"4. 管理既有 Webhooks","id":"4-管理既有-webhooks","depth":5},{"value":"驗證簽章","id":"驗證簽章","depth":2},{"value":"在您的伺服器上處理 Webhook 請求","id":"在您的伺服器上處理-webhook-請求","depth":4},{"value":"驗證 Webhook 簽章","id":"驗證-webhook-簽章","depth":4}],"frontmatter":{"seo":{"title":"Webhook"}},"lastModified":"2026-10-30T07:26:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/zh-tw/develop/webhook","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}