Skip to main content

​
Webhookとは

Webhookを使用すると、Rheel Chat APIで発生したイベント（メッセージ投稿、チャンネル作成など）を、あなたのサーバーにリアルタイムで通知できます。

​
主な用途

通知連携

メッセージ投稿時にメール通知やプッシュ通知を送信

外部システム連携

CRMやタスク管理ツールとの連携

ログ記録

チャットログを外部データベースに保存

自動応答

特定のキーワードに反応するBot機能の実装

​
Webhookの設定

​
1. エンドポイントURLの準備

Webhookを受け取るHTTPSエンドポイントを用意します。
WebhookエンドポイントはHTTPSである必要があります。HTTPは使用できません。

​
2. Webhook URLの登録

管理画面からWebhook URLを登録します。 Register Webhook Url Pn
  1. Dashboardにログイン
  2. アプリケーション設定を開く
  3. Webhook URLを入力して保存

​
3. イベントの選択

受け取りたいイベントを選択します： メッセージ系
  • channel:message_send - メッセージが投稿された
  • channel:message_update - メッセージが編集された
  • channel:messages_delete - メッセージが削除された
  • channel:mark_message_as_read - メッセージが既読になった
チャンネル系
  • channel:create - チャンネルが作成された
  • channel:update - チャンネルが更新された
  • channel:delete - チャンネルが削除された
  • channel:archive - チャンネルがアーカイブされた
  • channel:unarchive - チャンネルがアーカイブ解除された
ユーザー系
  • user:create - ユーザーが作成された
  • user:update - ユーザーが更新された
  • user:delete - ユーザーが削除された
チャンネル参加/退出系
  • channel:users_join - ユーザーがチャンネルに参加した
  • channel:users_leave - ユーザーがチャンネルから退出した
リアクション系
  • channel:message_reaction_add - リアクションが追加された
  • channel:message_reaction_remove - リアクションが削除された
添付ファイル系
  • channel:message_attachment_delete - 添付ファイルが削除された

​
Webhookペイロード

​
リクエストヘッダー

POST /your-webhook-endpoint
Content-Type: application/json
X-Rheel-Signature: sha256=...

​
ペイロード例（channel:message_send）

{
  "eventType": "channel:message_send",
  "application_id": "app_123",
  "occurred_at": "2025-03-21T10:00:00Z",
  "data": {
    "id": "msg_123",
    "channel_id": "ch_456",
    "user_id": "user_789",
    "text": "こんにちは",
    "created_at": "2025-03-21T10:00:00Z"
  }
}

​
ペイロード例（channel:message_update - 更新系）

更新系イベントにはchangesフィールドが追加されます： 
{
  "eventType": "channel:message_update",
  "application_id": "app_123",
  "occurred_at": "2025-03-21T10:05:00Z",
  "data": {
    "id": "msg_123",
    "channel_id": "ch_456",
    "user_id": "user_789",
    "text": "こんにちは（編集済み）",
    "updated_at": "2025-03-21T10:05:00Z"
  },
  "changes": [
    {
      "key": "text",
      "old": "こんにちは",
      "new": "こんにちは（編集済み）"
    }
  ]
}

​
署名検証

セキュリティのため、Webhookリクエストの署名を検証することを推奨します。 署名の検証にはアプリケーションのAPI Keyを使用します。 
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, apiKey) {
  const hmac = crypto.createHmac('sha256', apiKey);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// Express.jsの例
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-rheel-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.RHEEL_API_KEY  // アプリケーションのAPI Key
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // イベント処理
  const event = req.body;
  console.log('Received event:', event.eventType);

  res.status(200).send('OK');
});
署名検証には、管理画面で発行したアプリケーションのAPI Keyを使用してください。

​
レスポンス要件

Webhookエンドポイントは以下の要件を満たす必要があります：
  • HTTPステータスコード: 200-299の成功ステータスコードを返す（例: 200 OK, 204 No Content）
  • タイムアウト: 5秒以内にレスポンスを返す
  • 冪等性: 同じイベントが複数回送信される可能性があるため、冪等な処理を実装する
ネットワークエラーなどで配信に失敗した場合、最大3回まで自動的に再送されます。

​
リトライポリシー

Webhookの配信に失敗した場合、以下のスケジュールで再送されます：
試行回数待機時間
1回目すぐ
2回目1分後
3回目5分後
3回とも失敗した場合、そのイベントは破棄されます。

​
ベストプラクティス

Webhookハンドラー内で重い処理を行うと、タイムアウトが発生する可能性があります。イベントをキューに入れて非同期で処理することを推奨します。
同じイベントが複数回送信される可能性があるため、event_idなどを使用して重複処理を防ぎます。
処理に失敗した場合のデバッグのため、エラーログを記録してください。
悪意のあるリクエストを防ぐため、署名検証を必ず実装してください。

​
トラブルシューティング

​
Webhookが届かない

  1. エンドポイントURLが正しいか確認
  2. HTTPSを使用しているか確認
  3. ファイアウォール設定を確認
  4. サーバーログでエラーを確認

​
署名検証が失敗する

  1. Webhook Secretが正しいか確認
  2. ペイロードの文字列化が正しいか確認（改行、スペースなど）
  3. 署名アルゴリズムがsha256であることを確認

​
次のステップ

API Reference

Webhook設定APIの詳細を確認

リアルタイム通信

WebSocketとの使い分けを理解