Webhookにより、AgencyHandyは変更が発生した瞬間に外部システムへデータをプッシュできます — ポーリングは不要です。設定されたイベントが発生すると（例えば、注文が更新されたりチケットが作成されたりしたとき）、AgencyHandyは指定したエンドポイントURLにJSONペイロードを含むHTTP POSTリクエストを送信します。これにより、CRM、請求システム、カスタムダッシュボードなどの外部ツールをAgencyHandyワークスペースとリアルタイムで同期させることが容易になります。
Business Proプランのワークスペースでは、請求期間あたり最大30,000件のWebhookイベントがサポートされます。大量自動化を設定する前にプランの制限をご確認ください。
サポートされるイベント
以下のイベントの任意の組み合わせをWebhookに登録できます：
| カテゴリ | イベント |
|---|
| サービス | 作成、更新、削除 |
| 注文 | 作成、更新、削除 |
| タスク | 作成、割り当て、完了、更新 |
| 請求書 | ステータス変更 |
| クライアント / ユーザー | 新しいクライアントの追加、クライアント/ユーザーの削除 |
| 提案書 | 送信、受信、承認、却下 |
| チケット | 作成、割り当て、ステータス変更 |
| 支払い | 受信、失敗 |
| サービスパッケージ | 作成、更新、削除 |
Webhookを作成する
Webhook管理に移動する
左サイドバーでインテグレーション → Webhook管理に移動します。
トークンを認証する
管理ボタンをクリックして、WebhookトークンをAuthenticate します。このトークンは送信ペイロードに署名するために使用され、AgencyHandyから発信されたものであることを確認できます。
新しいWebhookを作成する
新しいWebhookを作成をクリックして、Webhook設定フォームを開きます。
エンドポイントURLを入力する
エンドポイントURLフィールドに、Webhookデータを受信する外部システムのURLを入力します。これは公開アクセス可能なPOSTエンドポイントである必要があります。
コンテンツタイプを選択する
コンテンツタイプとしてJSONを選択します。AgencyHandyはすべてのWebhookペイロードをapplication/jsonとして送信します。
Webhookイベントを選択する
このWebhookをトリガーするすべてのイベントを選択します。複数のカテゴリからイベントを選択できます — 例えば、注文：作成と請求書：ステータス変更の両方を同じエンドポイントに向けることができます。
Webhookを有効にする
アクティブラジオボタンをトグルします。アクティブな場合、AgencyHandyはすべての選択されたイベントのペイロードをリアルタイムでエンドポイントに配信します。
設定を保存する
設定を確認し、保存をクリックします。Webhookがリストに表示され、すぐにイベントの配信を開始します。
Webhookをテストする
Webhookを作成したら、テストペイロードを送信して、エンドポイントが到達可能でデータを正しく処理していることを確認します。
Webhookを開く
Webhook管理リストで、テストしたいWebhookをクリックします。
テストイベントをクリックする
Webhook詳細ページでテストイベントボタンをクリックします。
テストイベントを選択する
このWebhookに設定されているイベントのリストからサンプルイベントを選択します（例：注文：作成）。
テストペイロードを送信する
送信をクリックします。AgencyHandyがエンドポイントURLにサンプルペイロードを送信します。
結果を確認する
外部システムを確認して、テストペイロードが到着し、期待通りに処理されたことを確認します。AgencyHandyに戻り、Webhookをクリックして履歴を確認します — 完全なリクエスト、エンドポイントが返したレスポンスを確認でき、必要に応じて過去のイベントを再配信することもできます。
Webhookペイロードを認証する
AgencyHandyからの送信Webhookリクエストにはすべて、エンドポイントがペイロードの真正性を検証し、改ざんされていないことを確認するために使用できる署名ヘッダーが含まれています。
署名ヘッダー
AgencyHandyはすべてのWebhookリクエストにこのヘッダーを追加します。受信リクエストから値を抽出し、検証エンドポイントに渡します。
Webhook署名を検証する
以下のリクエストを送信してペイロードの真正性を確認します：
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
イベントを受信したWebhookのID。AgencyHandyのWebhook詳細ページで確認できます。
受信したWebhookリクエストのx-ah-sigヘッダーの値。
AgencyHandyのWebhook詳細ページに表示されるWebhookシークレット。
AgencyHandyのWebhookリクエストから受信した生のJSONボディ。
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';
const postData = {
webhookId: 'your_webhook_id',
signature: 'your_signature', // value of x-ah-sig header
secret: 'your_webhook_secret',
payload: {}, // the parsed JSON body from AgencyHandy
};
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(postData),
});
const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
署名が有効な場合はSUCCESS。検証に失敗した場合はFAILED（HTTP 403）。
{
"verification_status": "SUCCESS"
}
{
"type": "PermissionError",
"status": 403,
"verification_status": "FAILED"
}
Webhookシークレットは機密情報として扱ってください。定期的にローテーションし、ローテーション後はすぐに検証ロジックを更新してください。クライアントサイドのコードや公開リポジトリには絶対に公開しないでください。
重要な注意事項
- エンドポイントURLは公開アクセス可能なHTTPS POST URLである必要があります。
- エンドポイントが一時的に利用できない場合は、AgencyHandyのWebhook履歴パネルを確認してください — そこから直接任意の過去のイベントを再配信できます。
- 失敗した配信や不正アクセスの試みを検出するために、Webhookアクティビティを定期的に監視してください。
- 繰り返し失敗するWebhookはAgencyHandyによって一時停止される場合があります — 早期に問題を発見するために配信ログを確認してください。
