Benutzerdefinierte Integration

Die benutzerdefinierte Integration ermöglicht es Teams, vollständige Testdaten einfach von der axe DevTools-Erweiterung direkt an einen konfigurierbaren Webhook-Endpunkt zu senden. Dadurch können Sie einen benutzerdefinierten Webhook-Endpunkt einrichten, der axe DevTools-Testdaten verarbeiten kann.

So funktioniert es

Konfigurieren der Integration

Jeder Administrator des axe-Kontoportals kann die Integration konfigurieren.

1. Klicken Sie in der Navigationsleiste auf „KONFIGURATION“
2. Wählen Sie die Registerkarte „Integrationen“
3. Klicken Sie auf „Neue Verbindung zur benutzerdefinierten Integration hinzufügen“.
4. Geben Sie einen Namen ein (maximal 255 Zeichen)
5. Geben Sie Ihre Webhook URL an
6. Geben Sie ein Geheimnis an (siehe Authentifizierung unten)

Senden von Testergebnissen

Automatisches Festlegen von testId und url Abfrageparametern

Für den automatischen Testaufbau werden zwei Abfrageparameter unterstützt:

• testId: die Kennung des Tests innerhalb Ihrer internen Anwendung (z. B. 1234567)
• url: die URI-codierte Test-URL (z. B. https%3A%2F%2Fworkshop.dequelabs.com)

1. Link (oder navigieren Sie in Ihrem Browser) zu /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. Die Erweiterung axe DevTools erkennt die Test-ID automatisch und stellt die durchzuführenden Tests in die Warteschlange.
   • Wenn ein url Abfrageparameter angegeben wird, wird der Browser zu dieser URL navigiert
   • Wenn kein url Abfrageparameter angegeben ist, werden Sie aufgefordert, manuell zur URL zu navigieren
3. Öffnen Sie die Erweiterung axe DevTools, falls sie noch nicht geöffnet ist
4. Wählen Sie „Vollständiger Seitenscan“, „Teilweiser Seitenscan“ oder ein beliebiges IGT, um mit dem Testen zu beginnen
5. Sobald der Test abgeschlossen ist, navigieren Sie zur Registerkarte „Übersicht“ Ihres gespeicherten Tests
6. Öffnen Sie das Menü „Freigabeoptionen“
7. Klicken Sie auf die Option „Ergebnisse an benutzerdefinierte Integration senden“.
   • Wenn der konfigurierte Webhook-Endpunkt mit einem 2xx Antwortcode antwortet, wird eine Erfolgsmeldung ausgegeben
   • Wenn der konfigurierte Webhook-Endpunkt mit einem Nicht-2xx Antwortcode antwortet, wird eine Fehlermeldung ausgegeben

Manuelles Hinzufügen der Test-ID

1. Öffnen Sie die Erweiterung axe DevTools
2. Erstellen Sie einen neuen gespeicherten Test oder navigieren Sie zu einem vorhandenen Test
3. Sobald der Test abgeschlossen ist, navigieren Sie zur Registerkarte „Übersicht“ Ihres gespeicherten Tests
4. Öffnen Sie das Menü „Freigabeoptionen“
5. Klicken Sie auf die Option „Ergebnisse an benutzerdefinierte Integration senden“.
6. Geben Sie Ihre Test-ID ein
7. Klicken Sie auf "Senden"
   • Wenn der konfigurierte Webhook-Endpunkt mit einem 2xx Antwortcode antwortet, wird eine Erfolgsmeldung ausgegeben
   • Wenn der konfigurierte Webhook-Endpunkt mit einem Nicht-2xx Antwortcode antwortet, wird eine Fehlermeldung ausgegeben

Webhook-API

Dieser Abschnitt beschreibt den Webhook-Endpunkt zum Empfangen von Testergebnissen von axe DevTools.

Endpunktinformationen

URL-Struktur

Die URL-Struktur bleibt größtenteils Ihnen überlassen. Sie können jede beliebige Domäne und jeden beliebigen URL-Pfad verwenden (achten Sie jedoch darauf, bei der Konfiguration der benutzerdefinierten Integration die richtige URL einzugeben).

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

Authentifizierung

Die Authentifizierung wird mithilfe von Webhook-Signaturen implementiert. Jede Webhook-Anfrage enthält einen Signaturheader, der überprüft werden sollte, um sicherzustellen, dass die Anfrage von axe DevTools stammt.

Signaturprüfung

1. Ein geheimer Schlüssel wird zwischen axe DevTools und Ihrem Dienst geteilt
2. Die Signatur ist im X-Hub-Signature header enthalten
3. Format: X-Hub-Signature: sha256=<signature>
4. Zeitstempel X-Deque-Request-Timestamp: <ISO timestamp>
5. Überprüfen Sie die Signatur, indem Sie einen SHA-256 HMAC des Zeitstempels und des Anforderungstexts mit Ihrem ursprünglich bereitgestellten geheimen Schlüssel berechnen

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)
  )
}

Anforderungsheader

Anforderungstextschema

Die Webhook-Nutzlast folgt dem axe Universal JSON-Format. Nachfolgend finden Sie das detaillierte Schema mit Beispielen:

Beispiel-Payload

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

Antwortanforderungen

Ihr Webhook-Endpunkt muss:

• innerhalb von 10 Sekunden antworten
• Geben einen 2xx Statuscode für den erfolgreichen Empfang zurück

Fehlerbehandlung

Implementieren Sie eine entsprechende Fehlerbehandlung, indem Sie für diese Szenarien einen nicht-2xx-Statuscode zurückgeben:

• Ungültige Signatur
• Anforderungs-Timeout
• Fehlerhafte Nutzlasten
• Serverfehler