Webhook とトリガー

トリガーとは、Letaido が他のアプリで何かが起こったことをリアルタイムで検知する仕組みで、常に確認し続ける必要がありません。

HubSpot に新しい連絡先が追加されたとき、Slack で誰かがあなたを @メンションしたとき、取引がステージを移動したとき、Letaido はすぐにそれを検知して行動します。

これでできること

ここでチームが設定するものは次のようになります：

HubSpot のコンタクトが MQL になったとき、ICP に対してスコアリングし、結果を #mql-review に投稿します。
Slack ボットが #pmm-questions で @メンションされたとき、ブランドボイスで回答します。
Linear の課題に customer-facing のラベルが付けられたとき、1段落の公開用サマリーを作成し、PMM リードに DM で送信します。
GitHub のリリースが公開されたとき、ローンチメールを自動作成し、レビュー用に Notion に送信します。
Fathom のミーティングが終了したとき、アクションアイテムを抽出し、Linear に追加します。
Apify のスクレイパーが完了したとき、パイプラインの次のステージを開始します。

トリガーとアクションを平易な英語で記述します。エージェントが接続を設定し、一度承認を求めた後、自動的に実行されます。

内部の仕組み

2つのフレーバーがあります：

コネクタトリガー（推奨）。サードパーティサービスへの型付きサブスクリプションです。セットアップは1回の呼び出しで完了します。プラットフォームがサブスクリプション、署名シークレット、リトライロジック、イベントキューを処理します。イベントは既知のスキーマで到着します（Slack、GitHub、Linear、HubSpot、Fathom、Apify など）。
アドホック Webhook。まだ組み込みのコネクタトリガーがないサービスの場合、エージェントが汎用 Webhook URL を生成し、サードパーティがそこに POST するように設定し、同じキューにイベントをプルします。スキーマはサードパーティが送信するものになるため、少し多めの解析作業が必要になります。

いずれにせよ、エージェントが適切なものを選択します。あなたが選ぶわけではありません。

イベントの流れ

サードパーティサービスが、プラットフォームが所有する公開 URL に POST します。
プラットフォームは署名を検証し、ペイロードを解析し、エンリッチ処理（例：Slack のチャンネル ID を名前に解決）を行い、内部キューにプッシュします。
コンシューマー（アプリ、ジョブ、またはチャットエージェント）が、名前付きカーソルでキューをポーリングし、イベントを処理します。
各イベントは処理後に確認応答されます。未確認のイベントは、コンシューマーがクラッシュした場合に再配信されます。

カーソルはコンシューマーごとに管理されるため、コンソールアプリとジョブが互いに干渉することなく、同じイベントを監視できます。

Reliable と auto-ack の比較

自動確認（デフォルト）。 イベントを読み取ると、キューから即座に消えます。シンプルです。「フィードを追跡してテーブルに記録する」場合に適しています。
手動確認。 イベントを読み取り、処理してから、明示的に確認します。処理がクラッシュした場合、イベントは再配信されます。副作用（メール、データベースへの書き込み、ダウンストリーム API 呼び出し）を失ってはならない場合に使用します。

エージェントに「信頼性の高いワークフロー」を依頼すると、デフォルトで手動確認応答が選択されます。

よくある質問の形式

「新しい HubSpot コンタクトがライフサイクルステージ = marketingqualifiedlead で作成されたら、その企業を当社の ICP に照らしてスコアリングし、結果を #mql-review に投稿する。」

エージェント： 1. HubSpot の連絡先作成トリガーをサブスクライブします。 2. イベントを取得し、ICP スコアラーを呼び出し、Slack コネクタ経由で Slack に投稿する小さなコンシューマー（コンソールアプリまたはジョブ）を作成します。 3. 初回使用時には、HubSpot サブスクリプションの承認と Slack の承認の両方を表示します。

「GitHub の issue に pmm-review というラベルが付けられたら、顧客向けの要約を 1 段落で作成して DM してください。」

「誰かが #pmm-questions で Slack ボットに @メンションしたら、ブランドボイススキルを使って回答してください。」

ワークスペースに表示される内容

アクティブなサブスクリプションごとに： - コネクタとイベントタイプ。 - 署名シークレットのステータス。 - パブリック URL（アドホックの場合）またはサードパーティアプリの設定（コネクタトリガーの場合）。 - キューを読み取るコンシューマー。

ワークスペース UI からサブスクリプションを一時停止または取り消すことができます。取り消すと、それ以降のインバウンド POST に対して 410 が返されます。

制限とエッジケース

イベントが「チャットからのファンアウト」になることは決してありません。トリガーはサーバー駆動です。チャットセッションが閉じられても、イベントは引き続き到着し、コンシューマーが読み取るまでキューに蓄積されます。
キューには保持期間があります。数日以上経過した未読イベントは削除されます。コンシューマーがオフラインだった可能性がある場合は、イベントが欠落したと判断する前に確認してください。
公開サイトのコンシューマーには追加の制限があります。サイト表面のトリガーは、呼び出しごとに明示的なレビューが必要です（包括的な承認はありません）。これは、訪問者が制御するフローがファンアウトコストのリスクとなるためです。
署名シークレットは保存されますが、表示されることはありません。エージェントはそれらを使用できますが、読み取ることはできません。

内部の仕組み。 インバウンドイベントは nginx → api-proxy → connectors service に到達します。このサービスは、保存された署名シークレットに対して署名を検証し、コネクタのエンリッチフック（例：Slack のユーザー ID からユーザー名へのリゾルバー）を実行してから、webhook_events に行を書き込みます。コンシューマーは、オプションの provider および ack パラメータを使用して GET /webhooks/events?cursor=<name> 経由でプルします。手動確認応答のコンシューマーは、through_id を使用して /webhooks/ack に POST で返信します。