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

# Webhook 連携

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

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

## 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` | 通知記録と一緒に表示されるリンク。ダッシュボード、ログ、プルリクエストへの誘導に便利です。 |
| `notificationType` | `active`、`time-sensitive`、`calling` のいずれか。各購読者が選んだレベルを下げることしかできません。[通知レベル](#通知レベル)を参照してください。 |

### GET リクエスト

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

### POST リクエスト

JSON ボディを送信します：

```http
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` が送信するフォームエンコード形式のボディも使えます：

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

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

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

```json
{
  "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` で拒否され、通知は送信されません:

```json
{
  "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` でチャンネルをトリガーする呼び出し元がある場合はオフのままにしてください。

## 通知レベル

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

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

```bash
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 フィールドはすべて変数になります。

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

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

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

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

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

### テンプレート変数

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

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

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

### 特別な変数

- `externalLink`: リクエストに含めると、通知記録ビューでクリック可能なリンクを作成します（チャンネルに独自の外部リンクテンプレートがある場合を除く）。

```http
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.` 名前空間の下でのみ利用できます。完全な一覧と例は[条件](/ja/docs/conditions)を参照してください。

## 一般的なユースケース

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-のみ) がオンで、リクエストが `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. チャンネルにアクティブな購読者がいることを確認

ヘルプが必要ですか？[サポートセンター](/ja/docs/support)にアクセスするか、echobell@weelone.comまでお問い合わせください。
