Contents
連携方式の比較と実務での使い分け
主要な連携方式ごとに向き不向きを整理します。目的(単方向通知/双方向操作/イベント受信/公開エンドポイントが不要)に応じて選択してください。
Incoming Webhook(単方向通知)
外部から Slack へ一方向の通知を簡単に送る手段です。
- 概要:Slack で発行される webhook URL に JSON を POST するだけで通知できます。公式ドキュメント: https://api.slack.com/messaging/webhooks
- 長所:設定が簡単で外部サービス→Slack の通知に向きます。認証は URL 秘匿が中心です。
- チャネル上書きの注意:Webhook 作成時にデフォルトチャネルが設定されますが、ペイロードの channel パラメータで上書きすることが可能です。ただし上書きが有効になるかはアプリの権限やワークスペース設定に依存します。対象チャネルに投稿できる権限(ボットの参加や適切なスコープ)が無いとエラーになります。
- 推奨用途:監視アラート、フォーム通知、外部サービスからの単純な通知。
Bot via OAuth(Bot Token、双方向操作)
Bot トークンを用いて API を呼び、双方向の操作や読み取りを行う方式です。
- 概要:Slack アプリを OAuth でワークスペースにインストールし、Bot トークン(xoxb-)で API を呼びます。OAuth の公式ページ: https://api.slack.com/authentication/oauth-v2
- 長所:chat.postMessage、conversations.open、reactions.add などで双方向操作が可能です。ユーザーへの DM、メッセージ編集、モデレーションなど幅広く対応できます。
- 欠点:必要スコープの設計とインストールが必要です。ボットのチャネル参加状態や chat:write.public の有無で挙動が変わります。
- 推奨用途:ユーザー通知(DM)、自動応答、インタラクティブなワークフロー。
Events API(プッシュ受信)
Slack がイベントを公開エンドポイントへ POST する方式で、イベント駆動型の処理に適します。
- 概要:Slack がイベント(message, app_mention など)を登録した URL に送信します。Events API: https://api.slack.com/apis/connections/events-api
- 必要事項:公開エンドポイントか Socket Mode のどちらかが必要です。初回登録時の URL 検証(challenge 応答)と Signing Secret による署名検証が必須です(詳細は後述)。
- 長所:ポーリング不要で効率的にイベントを取得できます。
- 推奨用途:リアルタイムなメッセージ監視、インタラクション受信、ワークフローのトリガー。
Socket Mode / App‑Level Token(公開エンドポイントが取れない場合の代替)
公開エンドポイントを用意できない環境向けの代替手段です。
- 概要:App‑Level Token(xapp-)と Socket Mode を使うと、Slack と WebSocket 接続でイベントを受信できます。Socket Mode: https://api.slack.com/apis/connections/socket-mode
- 長所:ファイアウォールや NAT のために外部公開 URL を用意できない場合に有効です。イベント受信は持続接続で行います。
- 注意点:常時稼働するプロセスが必要です。Socket Mode でも Bot Token は API 呼び出しに必要です。Make へ直接受信させるには、中継プロセスで検証→転送する構成が現実的です。
Make の Webhook / HTTP モジュール(中継・処理プラットフォーム)
Make を受信→処理→転送のワークフローに利用する場合の実務的注意です。
- 概要:Make の Custom Webhook や HTTP モジュールで受け取り、処理や他 API への転送を行います。Make の公式ヘルプで Slack 連携を確認してください(Make 側のドキュメント参照)。
- 長所:受信→分岐→集約→転送をノーコード/ローコードで構築できます。
- 注意点:Make の Webhook だと raw body やヘッダが扱えない・扱いにくい場合があり、Signing Secret による厳密検証は外部ミドルウェア(サーバレス関数等)で行う方が確実です。Block Kit の渡し方(後述)もモジュールによって違いがある点に注意してください。
Slackアプリの作成とスコープ設計(最小権限)
Slack アプリを正しく作り、最小権限で運用するための手順と代表的なスコープの整理を示します。スコープは実際の API 呼び出し要件に合わせて最小化してください。
アプリ作成と基本設定手順
アプリ作成からインストールまでの基本フローです。
- api.slack.com にアクセスして「Create an app」からアプリを作成します。
- OAuth & Permissions で必要なスコープを追加し、リダイレクト URL を設定します。OAuth の公式ページ: https://api.slack.com/authentication/oauth-v2
- 必要に応じて Incoming Webhooks、Event Subscriptions、Interactivity(ボタン等)を有効化します。
- ワークスペースへインストールして Bot トークン(xoxb-)を取得します。
- Event Subscriptions を使う場合は公開 URL を登録し、Slack が送る url_verification の challenge に正しく応答できるよう実装します(詳細は後述)。
スコープを変更した場合は再インストールが必要です。まずはテストワークスペースで検証してください。
代表的スコープ(公式名称で統一)
下記は実務で頻出するスコープの例です。実際に必要なスコープは API メソッドのドキュメントで必ず確認してください(https://api.slack.com/scopes)。
- chat:write — Bot としてメッセージ送信(chat.postMessage 等)
- chat:write.public — Bot が参加していない公開チャンネルへの投稿を許可
- conversations:read — 会話(チャンネル・IM 等)の一覧取得
- conversations:history — 会話のメッセージ履歴の読み取り
- conversations:write — conversations.open など会話を作成・操作する権限
- reactions:read / reactions:write — 絵文字リアクションの読み書き
- users:read / users:read.email — ユーザー情報の取得(メールアドレス含む)
- incoming-webhook(機能の有効化) — Incoming Webhook 機能の有効化に関連
実装前に対応する API メソッドのページで要求スコープを確認してください。スコープの追加は再インストールと運用リスクの確認が必要です。
セキュリティの基本
最小権限と秘密情報の管理が重要です。
- Bot トークンや Signing Secret は安全なシークレット管理に格納し、ソース管理やログに記録しないこと。
- スコープは必要最小限に留め、変更履歴と影響範囲を管理すること。
- 定期的なトークンローテーション計画とアクセス監査を用意すること。
Makeでの接続とシナリオ作成(ステップバイステップ)
Make 上での実務的な準備とシナリオ構築のポイントを整理します。
事前準備
検証用のテスト環境を整え、Slack アプリと Make の設定を揃えます。
- テストワークスペースを用意し、開発用のアプリを作成してインストールします。
- Make 側で作業スペースと必要な接続(Slack, HTTP 等)を確認します。接続情報は接続ストアで管理し、シナリオにハードコードしないでください。
シナリオ作成手順(実務向け)
ここでは一般的な手順を示します。事前に認証情報とスコープを確認してください。
- Make で「Create a new scenario」を開始します。
- 必要モジュールを配置します(例:Webhooks / HTTP / Slack / Google Sheets)。
- Slack モジュールの認証を追加します。OAuth を使う場合は Make の OAuth フローでワークスペース承認を行います。
- Incoming Webhook を使う場合は Slack 側で Webhook URL を生成し、HTTP モジュールに設定します。HTTP モジュール使用時は Content-Type: application/json に注意してください。
- フィールドのマッピングは channel はできるだけ channel ID を使う運用にします。
- Run once で動作確認し、Make の実行ログと Slack の挙動を確認します。
- Error handler と Delay モジュールでリトライポリシーを作成します(429 等への対処)。
- シナリオを有効化し、段階的に本番へ移行します。
実務チェックポイント
運用を見据えたチェック項目です。
- 認証情報は Make の接続管理で保管し、シナリオに平文で埋め込まない。
- 環境差分(テスト/本番)の channel ID は変数化して管理する。
- Make のモジュールによってはヘッダや raw body にアクセスできない場合があるため、署名検証はミドルウェアで行うことを検討する。
代表的トリガー/アクション例と Block Kit 活用
実務で多いトリガー/アクションと、Block Kit の安全な扱い方を具体例で示します。
メッセージ監視(トリガー)
Events API や webhook を利用してメッセージを監視する方法です。
- 実装例:Events API で message.channels や app_mention をサブスクライブし、Make の Webhook で受け取ります。
- フィルタリング:Make 内で正規表現や文字列フィルタを使い、重要なメッセージのみ処理します。
- 注意点:conversations.history をポーリングで使うと効率が悪化します。可能な限り Events API/Socket Mode を使ってプッシュ受信する設計を推奨します。
メッセージ送信(アクション)
Bot がメッセージを送る典型的なパターンです。
- 実装例:Slack モジュールの Post a message(chat.postMessage)で channel ID、text、blocks を指定します。chat.postMessage: https://api.slack.com/methods/chat.postMessage
- DM 送信:conversations.open(必要なスコープは conversations:write)で得た channel ID を利用します。
- 公開チャネル投稿:Bot がメンバーでないチャネルへ投稿する場合は chat:write.public が必要です。可能ならボットをチャネルに招待する方が管理しやすいです。
リアクション操作
- 実装例:reactions.add は channel と timestamp を指定して実行します。スレッドや thread_ts の指定が必要な場合があります。
- 注意点:対象メッセージの権限や範囲により insufficient_scope や not_in_channel エラーが出ます。
チャンネル情報取得
- 実装例:conversations.list(scopes: conversations:read)で ID 一覧を取得し、conversations.info で詳細確認します。
- 注意点:結果のページネーションやスコープ不足に注意してください。
Block Kit の作り方(Make での実務ポイント)
Block Kit は JSON 配列で表現されます。ここでは Make 間の渡し方の違いに注意が必要です。
- 基本形(JSON 配列):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
[ { "type": "section", "text": { "type": "mrkdwn", "text": "*新しいアラート*:{{タイトル}}" } }, { "type": "actions", "elements": [ { "type": "button", "text": { "type": "plain_text", "text": "詳細" }, "value": "open_detail", "action_id": "open_detail" } ] } ] |
- Make の Slack モジュールと HTTP モジュールの違い:
- Slack モジュール(専用モジュール)では UI 上で blocks を配列として構築できる場合があります。Tools の JSON ビルダや配列ビルダを使うと安全です。
- HTTP モジュールで Slack API を直接呼ぶ場合は、必ず Content-Type: application/json を指定し、リクエストボディ全体を JSON として送信してください。blocks フィールドは JSON 配列である必要があり、文字列のまま二重引用符で送ると Slack 側で配列として解釈されず動作しません。必要なら JSON.stringify 相当で正しいシリアライズを行ってください。
- 変数埋め込み:Make で文字列連結して手作業で JSON を生成するとエスケープミスが発生しやすいです。Tools の JSON モジュールや配列ビルダを活用してください。
Interactivity と response_url の扱い
ボタン等のインタラクション受信時に使われる response_url の取り扱いについて説明します。
- 概要:インタラクションペイロード内に response_url が含まれる場合、受信側からその URL に対して HTTP POST することで即時応答や遅延更新が可能です。インタラクティビティの基本: https://api.slack.com/messaging/interactivity
- 利用時の注意:
- Slack はインタラクションに対して 3 秒以内の HTTP 200 応答(ack)を期待します。長い処理はレスポンスを返した後に response_url を使って更新すると良いです。
- response_url は用途に応じて短期間の有効性や利用制限があるため、長期的な更新や複数回更新が必要な場合は bot トークンで chat.update を使う方が確実です。
- response_url が必ず含まれるわけではありません。ペイロードの種類により未提供のケースがあるため、ペイロードでの存在チェックを行ってください。
運用・セキュリティ・トラブルシューティング(署名検証、レート制御、テンプレ)
運用でよく起きる課題と対処法、実装テンプレートを示します。特に署名検証とレート制御は厳密に実装してください。
Events API の URL verification(challenge)の正しい応答形式
URL 検証時の正しい応答は JSON 形式で challenge フィールドを返すことです。
- 要点:Slack が type=url_verification の POST を送るので、body から challenge を取り出し、HTTP 200 で次の JSON を返してください。Content-Type: application/json を明示することが必要です。
例(レスポンスボディ):
|
1 2 3 4 |
{ "challenge": "XXXXXXXXXXXXXXXXXX" } |
- 実装上の注意:レスポンスはプレーンテキストではなく JSON で返す必要があります。Content-Type ヘッダを必ず application/json に設定してください。
Signing Secret によるリクエスト検証(raw body を使う理由と実装注意)
署名検証で利用する「body」はパース済み JSON ではなく、リクエストの raw body(生のペイロード文字列)です。これを常に明確に扱ってください。
- 検証手順の概略:
- ヘッダ X-Slack-Request-Timestamp と X-Slack-Signature が存在するかを確認する。欠如時は拒否する。
- タイムスタンプ差分を検査し、リプレイを防ぐ(Slack 推奨は 5 分=300 秒程度)。
- raw body(例:Express なら raw body を取得する設定、Flask なら request.get_data(as_text=True))を用い、"v0:{timestamp}:{body}" を HMAC-SHA256 で signing secret と共に署名し、ヘッダの署名と定数時間比較する。
-
一致しなければ 401 等で拒否する。
-
実装サンプル(Python / Flask、簡略化):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
import time, hmac, hashlib from flask import Flask, request, abort, jsonify app = Flask(__name__) SIGNING_SECRET = "あなたの_Signing_Secret" @app.route("/slack/events", methods=["POST"]) def events(): ts = request.headers.get("X-Slack-Request-Timestamp") sig = request.headers.get("X-Slack-Signature") if ts is None or sig is None: abort(401) # タイムスタンプ差分チェック(リプレイ防止) if abs(time.time() - int(ts)) > 60 * 5: abort(401) # raw body を使う body = request.get_data(as_text=True) basestring = f"v0:{ts}:{body}".encode("utf-8") my_sig = "v0=" + hmac.new(SIGNING_SECRET.encode("utf-8"), basestring, hashlib.sha256).hexdigest() # 定数時間比較で検証 if not hmac.compare_digest(my_sig, sig): abort(401) data = request.get_json(silent=True) # 検証後にパースして処理 if data and data.get("type") == "url_verification": return jsonify({"challenge": data["challenge"]}) # 通常イベント処理へ return "", 200 |
- ログとエラーの扱い:エラー応答で秘密情報を返さないでください。SIGNING_SECRET、raw body、完全な署名値はログに出力しないこと。失敗ログはタイムスタンプやイベントタイプ、IP 等の最小限に留め、アクセス制御された監査ログに保存してください。
Make で署名検証が難しい場合の代替設計(ミドルウェア)
Make の Webhook が raw body/ヘッダを十分に扱えない場合は、軽量ミドルウェア(AWS Lambda / Cloud Function / Cloud Run 等)で署名検証を行い、検証済みの安全なペイロードを Make に転送する構成が推奨です。転送時に独自ヘッダ(X-Verified: true 等)を付与して信頼性を担保します。
Socket Mode でも同様に、受信したイベントの検証やフィルタリングを行ってから Make に流す設計が現実的です。
レート制御と再試行(Retry-After 優先と指数バックオフの具体例)
Slack API は 429 を返し、Retry-After ヘッダを付けることがあるため、Retry-After がある場合は優先的にその秒数だけ待機してください。Retry-After が無い場合は指数バックオフを使います。
- 実装パターン(擬似コード):
- 試行回数 max_attempts = 5
- 初期遅延 base = 1 秒、倍率 factor = 2、最大遅延 max_delay = 60 秒
- 失敗(429)の場合、レスポンスに Retry-After があれば int(Retry-After) 秒待機してリトライ
- Retry-After が無い場合は delay = min(base * factor*attempt, max_delay) + jitter(例:0~delay0.1 のランダム)
-
max_attempts 超過で失敗として上げる
-
Make 上の実装:HTTP モジュールのレスポンス判定→Delay モジュールで待機→再実行、または外部キューに入れて逐次処理する。大量イベント時は外部キュー(SQS, Pub/Sub, DB 等)で平準化し、Make 側は一定レートで処理することを検討してください。
-
Make のプラン制限対策:シナリオ分割、実行スケジュールの分散、外部キューを組み合わせて全体の実行数を抑制します。プランごとの実行数は Make の管理画面で確認してください。
よくあるエラーと対処法(短いリファレンス)
- insufficient_scope:要求した操作のスコープが付与されていません。該当スコープを追加し、再インストールしてください。
- invalid_auth:トークンが無効または期限切れです。接続情報を更新して OAuth 再承認してください。
- not_in_channel:Bot がチャネルに参加していません。ボットを招待するか、chat:write.public を検討してください。
- rate_limited(429):Retry-After を参照して待機、指数バックオフを実装してください。
- challenge failed:Events API の URL 検証で challenge を JSON で返しているか確認してください。
テスト・デバッグ手順
- Make の Run once で個別モジュールを検証する。
- curl で擬似ペイロードを送って受信系を検証する(署名検証は raw body を生成して同様に作成)。
- Slack 側の App 管理画面で Request Logs / Event Logs を確認する。
- 署名検証はユニットテスト化して自動的に検出できるようにする。
まとめ
- 目的に応じて Incoming Webhook/Bot(OAuth)/Events API/Socket Mode を使い分けてください。公開エンドポイントが不要なら Socket Mode を検討します。
- スコープは公式名称(例:chat:write, chat:write.public, conversations:read, conversations:history, conversations:write, reactions:write, users:read)で最小限に設計し、スコープ変更時は再インストールを必ず行ってください。
- Events API の URL 検証は JSON で {"challenge":"..."} を返し、Content-Type: application/json を指定してください。署名検証では raw body を使い、ヘッダ存在チェックとタイムスタンプ差(5 分程度)をチェックしてください。
- Make 単体で署名検証が困難な場合はミドルウェアで検証してから Make に転送する設計を推奨します。
- レート制御は Retry-After を優先し、無ければ指数バックオフ+ジッタで対処してください。大量イベント時は外部キュー化やシナリオ分割で平準化します。
- Block Kit はモジュール間の渡し方(配列として渡すか、HTTP の生 JSON として渡すか)に注意してください。誤った文字列化は動作不良の原因になります。
参考リンク(公式優先、実装前に必ず最新仕様を確認してください)
- Slack API ホーム: https://api.slack.com/
- OAuth & Permissions: https://api.slack.com/authentication/oauth-v2
- Scopes リファレンス: https://api.slack.com/scopes
- Events API: https://api.slack.com/apis/connections/events-api
- Verifying requests from Slack(署名検証): https://api.slack.com/authentication/verifying-requests-from-slack
- Incoming Webhooks: https://api.slack.com/messaging/webhooks
- Block Kit: https://api.slack.com/block-kit
- Socket Mode: https://api.slack.com/apis/connections/socket-mode
- Rate limits の概要: https://api.slack.com/docs/rate-limits
- Interactivity の取り扱い: https://api.slack.com/messaging/interactivity
非公式記事を参照する場合は参考情報として扱い、実装方針の根拠は必ず上の公式ドキュメントで再確認してください。API のエラーコードやスコープ等は更新される可能性があるため、実装時に最新の公式ドキュメントを確認する運用ルールを設けてください。