Webhookwebhook を登録する
Sofia に戻る

Webhook

webhook を登録する

Sofia が署名付き JSON で呼び出す https URL を登録します。最大 5 回再試行。シークレットは 1 回のみ表示、最大 10 件。

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

webhook を登録する

Sofia が署名付き JSON で呼び出す https URL を登録します。最大 5 回再試行。シークレットは 1 回のみ表示、最大 10 件。

認可

Authorizationstring必須

個人キーまたは OAuth アクセストークン。Bearer <token> として送信します。

このタブ内にのみ保持され、api.sofia-post.com にのみ送信されます。 API キーを取得

ボディ

このリクエストは、実際のアカウントに対して実行されます。

Webhook を登録する

公開の https アドレスと、受け取りたいイベントを登録します。署名シークレット（whsec_…）は、このレスポンスでしか表示されません。1 つのアプリで最大 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 は各イベントを JSON 形式 { id, type, createdAt, data } で POST し、ヘッダー 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 回まで試みます。
  • 同じイベントが 2 回届くことがあります。Sofia-Event-Id で重複を除いてください。
  • すばやく応答し、イベントの処理はそのあとで行ってください。

認可

  • Authorizationstringheader必須

    個人キーまたは OAuth アクセストークン。Bearer <token> として送信します。

ボディ

application/json
  • urlstring必須

    Sofia が呼び出す https の URL。プライベート、ループバック、リンクローカルのアドレスに解決されるホストは拒否されます

  • eventsstring[]必須

    受信するイベント

レスポンス

webhook と署名シークレット。シークレットは 1 回だけ表示されます。

  • idstring必須

    webhook の ID

  • urlstring必須

    Sofia が呼び出す URL

  • eventsstring[]必須

    購読中のイベント

  • createdAtstring<date-time>必須

    webhook が登録された日時

  • secretstring必須

    各配信に署名する HMAC-SHA256 キー（Sofia-Signature）。表示されるのはこの 1 回だけです

このページは役に立ちましたか？