Webhook註冊 webhook
返回 Sofia

Webhook

註冊 webhook

註冊 Sofia 以帶簽章 JSON 事件呼叫的 https URL，失敗最多重試五次。金鑰僅顯示一次，最多 10 個。

POSThttps://api.sofia-post.com/api/v1/webhooks
POSThttps://api.sofia-post.com/api/v1/webhooks

註冊 webhook

註冊 Sofia 以帶簽章 JSON 事件呼叫的 https URL，失敗最多重試五次。金鑰僅顯示一次，最多 10 個。

授權

Authorizationstring必填

你的個人金鑰或 OAuth 存取權杖，以 Bearer <token> 傳送。

僅保存在此分頁中，且僅傳送到 api.sofia-post.com。 取得 API 金鑰

請求本文

此請求將作用於你的真實帳號。

註冊 Webhook

註冊一個公開的 https 地址和你想要的事件。簽名金鑰（whsec_…）只會出現在這次回應中。一個應用程式最多可以有 10 個 Webhook。

curl -X POST https://api.sofia-post.com/api/v1/webhooks \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://app.example.com/hooks/sofia","events":["post.published","post.failed"]}'

事件

事件data
post.publishedpostId、establishmentId、platform、publishedAt、permalink
post.failedpostId、establishmentId、platform、error
webhook.testwebhookId

Sofia 以 POST 方式傳送每個事件，格式為 JSON { id, type, createdAt, data }，並帶有 Sofia-Event-Id、Sofia-Event-Type 和 Sofia-Signature 請求標頭。只有由你的應用程式建立的帖文才會被通知。

驗證簽名

Sofia-Signature 的值為 t=<unix time>,v1=<hex>，其中 v1 是用你的金鑰對 <t>.<raw body> 計算的 HMAC-SHA256。請對原始請求本文驗證，並拒絕過舊的時間戳：

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

const isSignedBySofia = (header, rawBody, secret) => {
  const parts = Object.fromEntries(
    (header ?? '').split(',').map((part) => part.trim().split('=', 2)),
  );
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || typeof parts.v1 !== 'string') return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
};

投遞與重試

  • 返回 2xx 即表示事件已送達。任何其他回應、重新導向（從不跟隨）或 10 秒無回應，都會在 1 分鐘、5 分鐘、30 分鐘和 2 小時之後觸發重試，最多重試 5 次。
  • 同一個事件可能到達兩次：請根據 Sofia-Event-Id 去重。
  • 請盡快回應，之後再處理事件。

授權

  • Authorizationstringheader必填

    你的個人金鑰或 OAuth 存取權杖，以 Bearer <token> 傳送。

請求本文

application/json
  • urlstring必填

    Sofia 呼叫的 https 地址。解析到私有、迴路或連結本機地址的主機會被拒絕

  • eventsstring[]必填

    要接收的事件

回應

webhook 及其簽章金鑰，僅顯示一次。

  • idstring必填

    webhook 的識別碼

  • urlstring必填

    Sofia 呼叫的地址

  • eventsstring[]必填

    已訂閱的事件

  • createdAtstring<date-time>必填

    webhook 的註冊時間

  • secretstring必填

    為每次遞送簽章的 HMAC-SHA256 金鑰（Sofia-Signature）。僅此一次顯示

這個頁面對你有幫助嗎？