カスタム統合

カスタム統合を利用することで、axe DevTools拡張機能からテストデータ全体を設定可能なwebhookエンドポイントに手軽に直接送信できます。これにより、axe DevTools テストデータを受信・処理できるカスタムWebhookエンドポイントを構築することができます。

動作概要

統合の設定

任意のaxe Account Portal管理者が統合を設定できます。

1.ナビゲーションバーの「CONFIGURATION」をクリックします。 1.「統合」タブを選択してください。 1.「カスタム統合に新しい接続を追加」をクリックします 1.名前を入力してください（最大255文字） 1.WebhookのURLを入力してください 1.シークレットを入力してください（詳細は認証(#authentication)を参照）

テスト結果の送信

testIdおよびurlクエリパラメータの自動設定

自動テストのセットアップでは、次の2つのクエリパラメータがサポートされています。

• testId：社内アプリケーション内のテストの識別子（例：1234567）。
• url：URIエンコードされたテストURL（例：https%3A%2F%2Fworkshop.dequelabs.com）。

1.「/axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com」にアクセスしてください。(https://axe.deque.com/axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com) 1.axe DevTools Extension（アックス・デブツールズ・エクステンション）はtestIdを自動的に認識し、テストの実行をキューに入れます。

• url クエリパラメータが指定された場合、ブラウザーはそのURLに遷移します。
• url クエリパラメータが指定されていない場合、手動でURLに移動するように求められます

1.axe DevTools拡張機能が開いていない場合は、開いてください。 接続済みカスタム統合拡張機能のテスト開始画面のスクリーンショット(images/custom-integration-connected.png) 1.「フルページスキャン」、「部分ページスキャン」、または任意のIGTを選択し、テストを開始してください。 1.テストが完了したら、保存したテストの「概要」タブに移動します。 1.「共有オプション」メニューを開いてください。 「結果をカスタム統合に送信」メニューオプションのスクリーンショット(images/custom-integration-send-button.png) 1.「結果をカスタム統合に送信する」をクリックしてください。 カスタム統合送信成功時のスクリーンショット(images/custom-integration-send-success.png)

• 設定されたWebhookエンドポイントが2xxのレスポンスコードを返した場合、成功メッセージが表示されます。
• 設定されたWebhookエンドポイントが2xx以外のレスポンスコードを返した場合、エラーメッセージが表示されます。

テストIDの手動追加

1.axe DevTools拡張機能を開いてください 1.新しいテストを作成するか、既存のテストを開いてください。 1.テストが完了したら、保存したテストの「概要」タブに移動します。 1.「共有オプション」メニューを開いてください。 1.「結果をカスタム統合に送信する」をクリックしてください。 「結果をカスタム統合に送信」メニューオプションのスクリーンショット(images/custom-integration-send-button.png) 1.テストIDを入力してください 1.「送信」をクリック

• 設定されたWebhookエンドポイントが2xxのレスポンスコードを返した場合、成功メッセージが表示されます。
• 設定されたWebhookエンドポイントが2xx以外のレスポンスコードを返した場合、エラーメッセージが表示されます。

ウェブフックAPI

このセクションでは、axe DevTools（アックス・デブツールズ）からテスト結果を受信するためのwebhookエンドポイントについて説明します。

エンドポイント情報

URL構造

URL構造はほとんどご自由に設定できます。任意のドメインとURLパスを使用できます（カスタム統合を構成する際は、正しいURLを入力してください）。

POST https://[your-domain]/[webhook-endpoint]

認証

認証はWebhook署名を使用して実装されます。各Webhookリクエストには署名ヘッダーが含まれており、これを検証してリクエストがaxe DevToolsからのものであることを確認する必要があります。

署名検証

1.秘密鍵はaxe DevToolsとご利用のサービス間で共有されます 1.署名は X-Hub-Signature ヘッダーに含まれます。 1.形式： X-Hub-Signature: sha256=<signature> 1.タイムスタンプ X-Deque-Request-Timestamp: <ISO timestamp> 1.最初に提供された秘密鍵を使用し、タイムスタンプとリクエストボディを入力として HMAC-SHA-256 を計算し、署名を検証してください。

Example signature verification (node):

import crypto from 'crypto'

function verifyWebhookSignature(payload, timestamp, signature, secret) {
  const expectedSignatureBody = Buffer.from(timestamp + JSON.stringify(payload), 'utf8')
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(expectedSignatureBody)
    .digest('base64')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

リクエストヘッダー

リクエストボディのスキーマ

WebhookペイロードはaxeユニバーサルJSONフォーマット(devtools-server/common-export-format)に準拠しています。詳細なスキーマとその例を以下に示します。

ペイロードの例

{
  "source": {
    "productName": "axe DevTools Enterprise",
    "productComponentName": "axe-core",
    "productVersion": "4.7.2"
  },
  "testDetails": {
    "testId": "test-123e4567-e89b",
    "integrationTestId": "your-test-id-123456",
    "startDate": "2025-01-09T10:00:00Z",
    "endDate": "2025-01-09T10:01:00Z",
    "engine": "axe-core",
    "axeVersion": "4.7.2",
    "standard": "WCAG 2.1 AA",
    "bestPracticesEnabled": true,
    "experimentalEnabled": false,
    "testName": "Homepage Accessibility Scan",
    "createdBy": "john.doe@example.com"
  },
  "allIssues": [
    {
      "issueId": "issue-123",
      "ruleId": "color-contrast",
      "description": "Elements must have sufficient color contrast",
      "help": "Elements must meet minimum color contrast ratio requirements",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.7/color-contrast",
      "impact": "serious",
      "needsReview": false,
      "isExperimental": false,
      "isManual": false,
      "summary": "Button text does not have sufficient contrast with background",
      "selector": [["#main-nav", "button.login"]],
      "tags": ["wcag2aa", "wcag143"],
      "createdAt": "2025-01-09T10:00:30Z",
      "testUrl": "https://example.com/homepage"
    }
  ]
}

応答要件

Webhookエンドポイントは、以下の要件を満たしている必要があります。

• 10秒以内に応答する。
• 2xx のステータスコードを返してください（受信が成功した場合）。

エラー処理

これらのシナリオに対しては、適切なエラー処理を実装し、2xx以外のステータスコードを返してください。

• 無効な署名。
• リクエストタイムアウト。
• 形式不正なペイロード。
• サーバーエラー。