Individuelle Integration

Die individuelle Integration ermöglicht es Teams, die gesamten Testdaten aus der axe DevTools-Erweiterung einfach direkt an einen konfigurierbaren Webhook-Endpunkt zu senden. Dadurch können Sie einen individuellen Webhook-Endpunkt einrichten, der axe DevTools-Testdaten verarbeiten kann.

Funktionsweise

Integration konfigurieren

Jeder Admin des axe Account-Portals kann die Integration konfigurieren.

1. Klicken Sie in der Navigationsleiste auf „KONFIGURATION“
2. Wählen Sie den Tab „Integrationen“
3. Klicken Sie auf „Neue Verbindung zur individuellen Integration hinzufügen“
4. Geben Sie einen Namen an (maximale Zeichen: 255)
5. Geben Sie Ihre webhook URL an
6. Geben Sie ein Geheimnis an (siehe Authentifizierung unten)

Testergebnisse senden

Automatisches Setzen von testId und url Abfrageparametern

Für die automatische Testeinrichtung werden zwei Abfrageparameter unterstützt:

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

1. Verlinken Sie (oder navigieren Sie Ihren Browser) zu /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. Die axe DevTools-Erweiterung erkennt automatisch die testId und stellt die durchzuführenden Tests in die Warteschlange
   • Wenn ein url Abfrageparameter bereitgestellt wird, wird der Browser auf die angegebene URL weitergeleitet
   • Wenn kein url Abfrageparameter bereitgestellt wird, werden Sie aufgefordert, manuell zur URL zu navigieren
3. Öffnen Sie die axe DevTools-Erweiterung, falls sie nicht bereits geöffnet ist
4. Wählen Sie „Vollständiger Seitenscan“, „Teilseitenscan“ oder ein beliebiges IGT, um mit dem Testen zu beginnen
5. Sobald das Testen abgeschlossen ist, navigieren Sie zum Tab „Überblick“ Ihres gespeicherten Tests
6. Öffnen Sie das Menü „Freigabeoptionen“
7. Klicken Sie auf die Option „Ergebnisse an individuelle Integration senden“
   • Wenn der konfigurierte Webhook-Endpunkt mit einem 2xx Antwortcode antwortet, wird eine Erfolgsmeldung angezeigt
   • Wenn der konfigurierte Webhook-Endpunkt mit einem anderen als 2xx Antwortcode antwortet, wird eine Fehlermeldung angezeigt

Test-ID manuell hinzufügen

1. Öffnen Sie die axe DevTools-Erweiterung
2. Erstellen Sie einen neuen gespeicherten Test oder navigieren Sie zu einem bestehenden
3. Sobald das Testen abgeschlossen ist, navigieren Sie zum Tab „Überblick“ Ihres gespeicherten Tests
4. Öffnen Sie das Menü „Freigabeoptionen“
5. Klicken Sie auf die Option „Ergebnisse an individuelle 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 angezeigt
   • Wenn der konfigurierte Webhook-Endpunkt mit einem anderen als 2xx Antwortcode antwortet, wird eine Fehlermeldung angezeigt

Webhook-API

In diesem Abschnitt wird der Webhook-Endpunkt für den Empfang von Testergebnissen von axe DevTools beschrieben.

Endpunktinformation

URL-Struktur

Die URL-Struktur liegt größtenteils bei Ihnen. Sie können jede beliebige Domain und jeden gewünschten URL-Pfad verwenden (achten Sie nur darauf, die korrekte URL bei der Konfiguration der benutzerdefinierten Integration einzugeben).

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

Authentifizierung

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

Signaturüberprü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 Anforderungstextes mit Ihrem ursprünglich bereitgestellten geheimen Schlüssel berechnen

Beispiel zur Signaturüberprüfung (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)
  )
}

Anforderungs-Header

Schema des Anforderungstextes

Die Webhook-Nutzlast folgt dem axe Universal JSON-Format. Unten ist das detaillierte Schema mit Beispielen aufgeführt:

Beispielhafte Nutzlast

{
  "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
• Einen 2xx-Statuscode für den erfolgreichen Empfang zurückgeben

Fehlerbehandlung

Implementieren Sie eine angemessene Fehlerbehandlung, indem Sie in diesen Szenarien einen nicht-2xx-Statuscode zurückgeben:

• Ungültige Signatur
• Zeitüberschreitung der Anfrage
• Fehlformatierte Nutzlasten
• Serverfehler