自動化Webhook
Sofia に戻る

自動化

Webhook

Sofia の投稿が公開された時や失敗した時に、別のシステムへ通知します。API で登録する署名つき Webhook で、再試行にも対応します。

Webhook は、投稿が公開された時や失敗した時に、Sofia が実行する HTTP 呼び出しです。スプレッドシートに内容を反映したり、メッセージツールに通知したり、Zapier や n8n のシナリオを起動したりできます。

追加する

  • 1. アドレスを指定します。 Sofia がイベントを送る、公開の https アドレスです。
  • 2. イベントを選びます。 post.published と post.failed です。
  • 3. 登録します。 POST /v1/webhooks：署名シークレット（whsec_…）は、このレスポンスでしか表示されません。
  • 4. テストを送ります。 POST /v1/webhooks/{id}/test で、他と同じ署名つきの webhook.test イベントが送られます。

リクエストの詳細は API タブにあります：Webhook の登録。通知されるのは、あなたのアプリが作成した投稿だけです。

受信側を作る

まずテストを送り、受け取ったボディを保管してください。これが契約内容であり、どんな説明よりも確かです。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 です。生のボディで計算し、古いタイムスタンプは拒否してください。
  • `2xx` をすばやく返し、処理はそのあとで行います。遅いエンドポイントは、停止しているエンドポイントと区別がつきません。
  • 冪等にします。 同じイベントが 2 回届くことがあります。Sofia-Event-Id で重複を除いてください。

Webhook が発火しなくなった時

アドレスに到達できない

Sofia は自社のサーバーから呼び出すので、アドレスは公開の https でなければなりません。リダイレクトは追跡せず、10 秒間応答がなければ失敗として扱います。

アドレスがエラーを返す

2xx 以外の応答があると、1 分後、5 分後、30 分後、2 時間後に再試行し、最大 5 回まで試みます。まず自分のログを確認し、POST /v1/webhooks/{id}/test で再現してください。

投稿があなたのアプリで作成されていない

Webhook が通知するのは、あなたのアプリが作成した投稿だけです。画面から作成した投稿では発火しません。

Webhook は、Sofia が動作した時に知らせます。Sofia を動かすには、Sofia API、sofia CLI、MCP サーバー（API タブと Agents タブ）、またはサードパーティ連携を使ってください。

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