Webhook連携 - HTTPトリガー完全ガイド

Echobellのwebhookをアプリやサービスに組み込む方法を解説。HTTPメソッド、変数、テンプレート、ヘッダー、即時通知のための実践的な連携例を含む完全ガイド。


Webhookは、Echobell通知をトリガーする最も汎用性の高い方法です。この包括的なガイドでは、webhookベースのアラートをシステムに統合するために必要なすべてを網羅します(基本概念から高度な使用パターンまで)。

Direct キーを使っていましたか? Direct キーはチャンネルになりました。 お使いのキーはそれぞれ同じ名前のチャンネルに変換され、以前の https://hook.echobell.one/d/… URL もこれまでとまったく同じように動作するため、 スクリプトを変更する必要はありません。新しい連携では、アプリに表示される チャンネルの /t/ webhook URL を使えます。受け付けるフィールドは同じです。 /t/ URL では notificationType で購読時に選んだレベルを下げることしかできない (通知レベルを参照)ため、スクリプトが calling を指定する場合は チャンネルを「通話」で購読してください。

webhook とは

webhook は、あるアプリケーションが他のアプリケーションにリアルタイムで情報を提供する方法です。誰かに電話番号を渡すようなものです - その番号に電話をかけると、あなたの電話が鳴ります。デジタルの世界では、あるシステムで何かが起きた時に、あなたが提供した URL(webhook)に HTTP リクエストを送信し、あなたのシステムでアクションをトリガーします。

例えば、サーバーの CPU 使用率が高すぎくなった時、監視システムが Echobell の webhook URL を呼び出し、それによってあなたに警告する通知がトリガーされます。これは自動的にリアルタイムで発生し、あなたが手動で CPU 使用率を確認する必要はありません。

webhook エンドポイントとは?

webhook エンドポイントとは、webhook リクエストを受け取る URL のことです。送信側のサービスにこのアドレスを貼り付けると、サービスは各イベントの送り先がわかります。送信側はその URL に HTTP リクエスト(通常は JSON ボディ付きの POST)を送り、エンドポイントは 200 OK などのステータスコードを返して、イベントを受け取ったことを伝えます。

Echobell では、チャンネルごとに専用の webhook エンドポイントがあります(例:https://hook.echobell.one/t/<channel-token>)。これを webhook URL として Grafana、GitHub Actions、TradingView などのサービスに貼り付けると、そこへのリクエストがすべてチャンネルの購読者への通知になります。URL 内のトークンがチャンネルを識別するため、エンドポイントはパスワードと同じように扱ってください。

概要

Echobell では、チャンネルが webhook を受け取ります。各チャンネルには専用の webhook URL があり、その URL が呼び出されると、チャンネルはすべての購読者に通知を送信します。

チャンネルの作成に必要なのは名前だけです。デフォルトでは、チャンネルは各リクエストが送信した title、body、externalLink を送信されたとおりに表示します。自作のスクリプト、cron ジョブ、CI ステップに便利です。リクエストが他のサービスから送られてくる場合は、カスタムテンプレートをオンにして、リクエストのデータから通知を組み立てることもできます。

Webhook URL の形式

https://hook.echobell.one/t/{チャンネルトークン}

チャンネルの webhook URL は、Echobell アプリのチャンネル詳細ビューで確認できます。

Webhook リクエストの実行

デフォルトでは、チャンネルは各リクエストから 4 つのフィールドを読み取ります。フィールド名は大文字と小文字を区別せず(title、Title、TITLE は同じフィールドです)、GET のクエリ文字列、または JSON かフォームエンコード形式の POST ボディで送信できます。

フィールド説明
title通知のタイトル。デフォルトはチャンネル名です。
body通知の本文。デフォルトは空です。
externalLink通知記録と一緒に表示されるリンク。ダッシュボード、ログ、プルリクエストへの誘導に便利です。
notificationTypeactive、time-sensitive、calling のいずれか。各購読者が選んだレベルを下げることしかできません。通知レベルを参照してください。

GET リクエスト

GET https://hook.echobell.one/t/<channel-token>?title=Backup%20finished&body=Nightly%20backup%20completed

POST リクエスト

JSON ボディを送信します:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "title": "CPU alert",
  "body": "Production CPU usage reached 95%",
  "externalLink": "https://dashboard.example.com/alerts/123"
}

または、curl -d が送信するフォームエンコード形式のボディも使えます:

curl -d "title=Hello&body=World" https://hook.echobell.one/t/<channel-token>

ブラウザで URL を開いた場合

クエリ文字列もボディもない GET(ブラウザやチャットアプリのリンクプレビューが送信するもの)では、誰にも通知されません。代わりに、チャンネルは受け付けるフィールドの簡単な説明を返します:

{
  "success": true,
  "notificationTriggered": false,
  "message": "This is an Echobell channel webhook. It pushes a notification to the channel's subscribers. Send a title or a body to trigger one.",
  "usage": { "...": "..." }
}

通知を送るには title か body を追加してください。POST はボディが空でも必ず通知します(その場合、タイトルはチャンネル名になります)。

POST のみ

各チャンネルには、Echobell アプリの詳細設定に POST のみ スイッチがあります。デフォルトはオフです。

オンにすると、POST だけがチャンネルをトリガーできます。Webhook URL への GET は 405 Method Not Allowed で拒否され、通知は送信されません:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

HEAD リクエストは影響を受けません。POST のみのオン・オフにかかわらず 200 を返し、通知をトリガーすることはありません。

Webhook URL が、リンクを自動的に取得する場所(チャットのメッセージ、Wiki のページ、ブラウザのアドレスバーなど)に置かれる場合はオンにしてください。URL のプレビューや表示だけで通知が飛ぶことを防げます。GET でチャンネルをトリガーする呼び出し元がある場合はオフのままにしてください。

通知レベル

チャンネルを購読する人は、アプリでそのチャンネルの通知タイプを選びます:通常(active)、時間重要、通話。この選択が、チャンネルがその人に届けられる最も高いレベルです。リクエストは notificationType を送信してより低いレベルを求めることはできますが、より高いレベルを求めることはできません。

たとえば、「Production」チャンネルを通話で購読したとします。障害のリクエストは notificationType を省略するので、電話のように着信します。デプロイ完了などの定常的なイベントは notificationType=active を送信し、通常の通知として届きます:

curl -d "title=Deploy finished&body=v2.1.0 is live&notificationType=active" \
  https://hook.echobell.one/t/<channel-token>

同じチャンネルを時間重要で購読しているチームメイトには、障害は時間重要の通知として届き、通話になることはありません。

カスタムテンプレートをオンにしたチャンネルは、リクエストの notificationType を無視します。各購読者には常に自分が選んだレベルで届きます。

カスタムテンプレート

デフォルトでは、チャンネルは各リクエストが送信した title、body、externalLink を表示します。ペイロードを変更できないサービス(監視ツール、CI システム、ストアなど)からリクエストが届く場合は、チャンネル設定の詳細設定でカスタムテンプレートをオンにし、タイトルテンプレートと本文テンプレートを書きます。以降、チャンネルはすべての通知をそのテンプレートから組み立て、リクエストのクエリパラメータと JSON フィールドはすべて変数になります。

クエリパラメータで変数を渡します:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

または JSON ボディで渡します:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

テンプレート変数

{{変数名}}構文を使用して、通知テンプレートで変数を使います:

タイトル:サーバー{{server_name}}アラート
本文:CPU使用率が{{cpu_usage}}%に到達しました

トリガー時、これらのテンプレートは webhook リクエストで提供された値で置き換えられます。構文の詳細はテンプレートを、通知するリクエストを絞り込む方法は条件を参照してください。

特別な変数

  • externalLink: リクエストに含めると、通知記録ビューでクリック可能なリンクを作成します(チャンネルに独自の外部リンクテンプレートがある場合を除く)。
POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

システム時刻変数(UTC)

送信データに加えて、テンプレートと条件で常に利用できる読み取り専用のシステム時刻変数(UTC)があります。フラットなフィールドには date、time、year、month、dayOfWeek、hour、minute、second が含まれます。その他 — sys.dayOfWeekName、sys.epochMs、sys.epochSeconds など — は sys. 名前空間の下でのみ利用できます。完全な一覧と例は条件を参照してください。

一般的なユースケース

webhook は以下のような用途に特に便利です:

  • サーバー監視とアラート
  • CI/CD パイプライン通知
  • IoT デバイスのステータス更新
  • アプリケーションエラーの追跡
  • E コマースの注文通知
  • 自動化システムアラート

ベストプラクティス

  1. エラー処理: Echobell はすべての webhook 呼び出しに HTTP ステータスと JSON 本文で応答します。まず HTTP ステータスを確認し、次に notificationTriggered で通知が実際に送信されたかを確認してください:
    • 200 OK: リクエストは処理されました。notificationTriggered: true は通知が送信されたことを意味します。notificationTriggered: false は意図的に何も送信しなかったことを意味します。チャンネルの条件に一致しなかった (conditionsMet: false) か、パラメーターのない GET に使い方の説明を返した場合です。
    • 400 Bad Request: URL のトークンの長さが正しくありません。
    • 404 Not Found: このトークンを持つチャンネルがありません (code: "TRIGGER_TOKEN_NOT_FOUND"。旧 /d/ URL では DIRECT_KEY_NOT_FOUND)。チャンネルが削除されたか、webhook URL がリセットされています。
    • 405 Method Not Allowed: POST のみ がオンで、リクエストが POST ではありませんでした。
    • 413 Payload Too Large: リクエスト本文が 1 MiB を超えています。
    • 429 Too Many Requests: 同じ webhook URL に 1 分間で 120 件を超えるリクエストがありました。レスポンスには Retry-After ヘッダー (秒単位) が含まれるので、その時間待ってから再試行してください。
    • 500: 一時的なサーバーの問題です。指数バックオフで再試行してください。
  2. レート制限: 通知システムへの負荷を避けるため、webhook 呼び出しの間に適切な遅延を実装してください。各 webhook URL は 1 分あたり最大 120 件のリクエストを受け付け、それを超えると 429 を返します。
  3. データセキュリティ: webhook URL は信頼できるシステムとサービスとのみ共有してください
  4. テスト: 本番環境に実装する前に、最小限のデータで webhook 統合をテストしてください

プライバシーとセキュリティ

以下の点に注意してください:

  • webhook URL は機密情報として扱う必要があります
  • webhook リクエストには必要なデータのみを送信してください
  • すべての通知コンテンツは購読者のデバイスにローカルに保存されます
  • サーバーは webhook リクエストの処理と通知のルーティングのみを行います

トラブルシューティング

webhook が期待通りに動作しない場合:

  1. webhook URL が正しいことを確認
  2. チャンネルがアクティブであることを確認
  3. JSON ペイロードが正しくフォーマットされていることを確認(POST リクエストの場合)
  4. テンプレートで必要なすべての変数が提供されていることを確認(カスタムテンプレートを使うチャンネルの場合)
  5. チャンネルにアクティブな購読者がいることを確認

ヘルプが必要ですか?サポートセンターにアクセスするか、echobell@weelone.comまでお問い合わせください。