コンテンツにスキップ

Slack Webhook出力リファレンス

slack出力は、選択したAdderイベントを1つ以上のSlack Incoming Webhookへ 送信します。各Webhook URLはSlackの送信先に紐づく認証シークレットです。 Slackで送信先チャンネルごとのIncoming Webhookを作成し、URLを安全に管理してください。

このリファレンスでは、設定、イベントの選択、JSONペイロード、HTTP配信、 レート制限、再試行、エラー処理、停止時の動作を説明します。

  • Slackの送信先チャンネルごとにIncoming Webhook URLを作成します。
  • AdderがWebhook URLへHTTPS接続できることを確認します。
  • Webhook URLは安全に保管し、設定ファイルやログへ不用意に公開しないでください。

output: slackを選択し、plugins.output.slackにオプションを設定します。

output: slack
plugins:
output:
slack:
webhook-urls: "https://hooks.slack.com/services/EXAMPLE/ONE,https://hooks.slack.com/services/EXAMPLE/TWO"
event-types: "blocks,transactions,rollbacks,governance"

webhook-urlsにはカンマ区切りで1つ以上のURLを指定します。Adderは各項目の前後の空白を 除去し、空の項目を無視します。残ったURLが1つもない場合、またはURLの形式が不正な場合は 起動時に設定エラーになります。URLはhttpsスキームを使用し、ユーザー情報を含めないでください。

event-typesには1つ以上のサポート対象イベントをカンマ区切りで指定します。空の値や サポートされていないイベント名は設定エラーになります。イベント名は次の表に示す識別子を そのまま使用してください。

オプション必須既定値説明
webhook-urlsはいなしSlack Incoming Webhook URLのカンマ区切りリストです。各URLにはhttpsを使用し、ユーザー情報を含めません。
event-typesいいえblocks,transactions,rollbacks,governanceSlackへ配信するイベント識別子のカンマ区切りリストです。少なくとも1つのサポート対象イベントを指定します。

Webhook URLは送信先ごとの認証シークレットとして扱います。Adderは配信エラーをログと プラグインのエラーチャネルへ通知しますが、エラー内容にWebhook URLやそのシークレットを 含めません。

event-typesは次のイベント識別子を受け付けます。

識別子メッセージに含まれる情報
blocksブロック番号、スロット番号、Era、ブロックハッシュ、トランザクション数
transactionsトランザクションハッシュ、ブロック番号、スロット番号、手数料(lovelace)
rollbacksロールバック先のスロット番号とブロックハッシュ
governanceトランザクションハッシュ、スロット番号、提案数、投票数、DRep証明書数
drep-registrationDRep証明書の種類、DRep ID、トランザクションハッシュ、スロット番号
drep-updateDRep証明書の種類、DRep ID、トランザクションハッシュ、スロット番号
drep-retirementDRep証明書の種類、DRep ID、トランザクションハッシュ、スロット番号

既定ではblocks、transactions、rollbacks、governanceを選択します。 DRep証明書イベントはevent-typesに追加した場合に選択されます。選択しなかったイベントは Slackへ送信せず、Adderのパイプラインを通常どおり通過します。

Adderは選択したイベントをテキストメッセージへ整形し、次のJSON形式で各送信先へ個別に HTTP POSTします。複数の送信先を指定した場合、Adderは同じイベントを各URLへ個別に送信します。

POST https://hooks.slack.com/services/EXAMPLE/ONE
Content-Type: application/json
{"text":"Cardano rollback to slot 42\nHash: abc"}

リクエストボディはJSONオブジェクトのtextフィールドだけで構成します。メッセージ形式に 関する設定オプションはありません。Adderはイベントの種類、スロット番号またはブロック番号、 関連するハッシュまたは件数を含むテキストを作成します。

1つのイベントを送信するHTTPリクエストには次の制限があります。

  • 各送信先へのイベントは個別のリクエストで送信し、バッチ化しません。
  • 各HTTPリクエストのタイムアウトは15秒です。
  • Adderが読み取るHTTPレスポンスボディは最大1,024バイトです。
  • 配信処理の入力バッファーには上限があり、永続的なローカルキューはありません。

SlackがHTTPステータス200を返し、レスポンスボディがokの場合、Adderはその送信先への 配信成功として扱います。通常の成功リクエストの後、Adderは同じ送信先への次のリクエストを 少なくとも1秒間隔を空けて送信します。

SlackがHTTPステータス429を返した場合、AdderはRetry-Afterヘッダーを整数の秒数として 解析し、同じメッセージを再送します。

  • 有効なRetry-Afterの値が0秒以上1分以内の場合、その送信先にクールダウンを設定します。
  • 再試行回数を使い切った場合も、解析したクールダウンを後続イベントへ適用します。
  • Retry-Afterがない、整数として解析できない、または負の値の場合、該当イベントの配信を失敗とし、送信先に1分間のクールダウンを設定します。
  • 1分を超えるRetry-Afterは再試行可能な期間を超えるため、配信を失敗とします。設定した送信先はクールダウン中として後続リクエストを受け付けません。

クールダウンは送信先ごとに管理します。クールダウンが1分を超えて残っている間、Adderは その送信先への後続イベントをスキップします。残り時間が1分以内になると、残りのSlackの クールダウンが終わるまで待ちます。ある送信先の制限は他の送信先への配信を停止しません。

HTTPステータス5xxと一時的なHTTP接続エラーは、最大3回まで再試行します。再試行の待機時間には、 上限付きの指数バックオフ(1秒、2秒、4秒)を使用します。 その他のクライアントエラーと再試行回数を使い切ったエラーは、ログとプラグインのエラー チャネルへ通知します。

クールダウンはプロセス実行中の送信先状態として保持します。Adderはクールダウンや保留中の イベントを永続化しないため、プロセスを再起動した後に未完了のイベントを再送しません。

停止または実行コンテキストのキャンセルが発生すると、Adderは配信処理を終了し、実行中の HTTPリクエストをキャンセルします。配信処理の入力バッファーに残るイベントは送信を待たずに 破棄します。

配信エラーはログとプラグインのエラーチャネルへ送信します。エラーにはHTTPステータスや Retry-Afterの問題など、対処に必要な情報を含めますが、Webhook URLやURL内の認証シークレットを 含めません。

本番チャンネルとは別のテストチャンネルに、テスト用のSlack Incoming Webhookを作成します。 テスト用Webhook URLを本番の設定やログへコピーしないでください。

  1. テスト用Webhook URLをwebhook-urlsに指定し、output: slackを設定します。
  2. event-typesに含まれるイベントを1つ選択します。
  3. Adderを起動し、選択したイベントに一致するチェーンイベントを発生させます。
  4. 設定したテストチャンネルにメッセージが表示されることを確認します。
  5. ログとプラグインのエラーチャネルに配信エラーがないことを確認します。

設定やイベント選択の一覧はコマンドリファレンスを、他の出力プラグインへの 導線は出力連携リファレンスを参照してください。


Doc Holiday logo

Docs authored by Doc Holiday