カスタムインテグレーション

カスタムインテグレーションにより、チームはaxe DevTools Extensionからテストデータ全体を直接設定可能なWebhookエンドポイントに簡単に送信することができます。これにより、axe DevToolsテストデータを受け取ることができるカスタムWebhookエンドポイントを立ち上げることができます。

仕組み

インテグレーションの設定

どのaxeアカウントポータルの管理者もインテグレーションを設定できます。

1. ナビゲーションバーの「CONFIGURATION」をクリックします
2. 「Integrations」タブを選択します
3. 「カスタムインテグレーションへの新しい接続を追加」をクリックします
4. 名前を入力します（最大文字数：255）
5. webhook URLを入力します
6. シークレットを入力します（以下の認証を参照）

テスト結果の送信

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にリンクする（またはブラウザでナビゲートする）
2. axe DevTools Extensionは自動的にtestIdを認識し、実行するテストをキューに追加します
   • urlクエリパラメータが提供されると、ブラウザはそのURLにナビゲートします
   • urlクエリパラメータが提供されない場合、手動でのURLナビゲートが求められます
3. まだ開いていない場合はaxe DevTools Extensionを開きます
4. 「全ページスキャン」、「部分ページスキャン」、または任意のIGTを選択してテストを開始します
5. テストが完了したら、保存したテストの「概要」タブに移動します
6. 「共有オプション」メニューを開きます
7. 「結果をカスタムインテグレーションに送信」オプションをクリックします
   • 設定されたWebhookエンドポイントが2xx応答コードで応答した場合、成功メッセージが表示されます
   • 設定されたWebhookエンドポイントが2xx以外の応答コードで応答した場合、エラーメッセージが表示されます

テストIDの手動追加

1. axe DevTools Extensionを開く
2. 新しい保存テストを作成するか、既存のテストに移動します
3. テストが完了したら、保存したテストの「概要」タブに移動します
4. 「共有オプション」メニューを開きます
5. 「結果をカスタムインテグレーションに送信」オプションをクリックします
6. テストIDを入力します
7. 「送信」をクリックします
   • 設定されたWebhookエンドポイントが2xx応答コードで応答した場合、成功メッセージが表示されます
   • 設定されたWebhookエンドポイントが2xx以外の応答コードで応答した場合、エラーメッセージが表示されます

Webhook API

このセクションでは、axe DevToolsからテスト結果を受信するためのWebhookエンドポイントについて説明します。

エンドポイント情報

URL構造

URL構造はほとんどの場合、あなた次第です。任意のドメインとURLパスを使用できます（カスタム統合を設定する際には必ず正しいURLを入力してください）。

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

認証

認証はウェブフック署名を使用して実装されます。各ウェブフックリクエストには、axe DevToolsからのリクエストであることを確認するための署名ヘッダーが含まれています。

署名の検証

1. 秘密鍵はaxe DevToolsとあなたのサービスの間で共有されます
2. 署名はX-Hub-Signatureヘッダーに含まれています
3. フォーマット: X-Hub-Signature: sha256=<signature>
4. タイムスタンプX-Deque-Request-Timestamp: <ISO timestamp>
5. 最初に提供された秘密鍵を使用して、タイムスタンプとリクエストボディのSHA-256 HMACを計算することで署名を確認してください

署名の検証例（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)
  )
}

リクエストヘッダー

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

ウェブフックペイロードはaxe Universal JSON形式に従います。以下に詳細なスキーマと例を示します：

ペイロードの例

{
  "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"
    }
  ]
}

レスポンス要件

ウェブフックエンドポイントは次の条件を満たす必要があります：

• 10秒以内に応答する
• 正常に受信したことを示す2xxステータスコードを返す

エラーハンドリング

以下のシナリオに対して非2xxステータスコードを返すことで、適切なエラーハンドリングを実装してください：

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