Aangepaste integratie

Met de aangepaste integratie kunnen teams eenvoudig alle testdata vanuit de axe DevTools Extension direct naar een configureerbaar webhook-endpoint sturen. Hiermee kunt u een aangepast webhook-eindpunt opzetten dat axe DevTools-testgegevens kan ontvangen en verwerken.

Hoe het werkt

De integratie configureren

Iedere beheerder van het axe Account Portal kan de integratie configureren.

1. Klik op 'CONFIGURATIE' in de navigatiebalk.
2. Selecteert u het tabblad 'Integraties'
3. Klik op "Nieuwe verbinding toevoegen aan Aangepaste integratie"
4. Voer een naam in (maximaal 255 tekens)
5. Vul uw webhook(#webhook-api) URL in
6. Geef een secret op (zie authenticatie hieronder)

Testresultaten verzenden

Automatisch Instellen van testId en url Queryparameters

Voor automatische testconfiguratie worden twee queryparameters ondersteund:

• testId: de ID van de test in uw interne applicatie (bijvoorbeeld 1234567)
• url: de URI-gecodeerde test-URL (bijv. https%3A%2F%2Fworkshop.dequelabs.com)

1. Navigeer in uw browser naar /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. De axe DevTools Extension detecteert automatisch de test-ID en zet de uit te voeren tests in de wachtrij.
   • Als de url-queryparameter is opgegeven, wordt de browser automatisch naar de opgegeven URL geleid
   • Als er geen url queryparameter is opgegeven, wordt u gevraagd om handmatig naar de URL te navigeren.
3. Open de axe DevTools Extension indien deze nog niet geopend is. Schermafbeelding van de teststartpagina van de aangesloten aangepaste integratie-extensie.(images/custom-integration-connected.png)
4. Kies "Volledige pagina scannen", "Gedeeltelijke pagina scannen" of een IGT om het testen te starten.
5. Zodra de test is voltooid, ga naar het tabblad "Overzicht" van uw opgeslagen test.
6. Open het menu "Deelopties"
7. Klik op "Resultaten naar aangepaste integratie verzenden" Screenshot van geslaagde verzending naar aangepaste integratie(images/custom-integration-send-success.png)
   • Indien het geconfigureerde webhook-endpoint met een 2xx responscode antwoordt, wordt er een succesmelding weergegeven
   • Indien het geconfigureerde webhook-endpoint met een andere responscode dan 2xx antwoordt, wordt er een foutmelding weergegeven.

Handmatig een test-ID toevoegen

1. Open de axe DevTools Extension
2. Maak een nieuwe opgeslagen test aan of navigeer naar een bestaande test
3. Zodra de test is voltooid, ga naar het tabblad "Overzicht" van uw opgeslagen test.
4. Open het menu "Deelopties"
5. Klik op "Resultaten naar aangepaste integratie verzenden"
6. Voer uw test-ID in
7. Klik op "Verzenden"
   • Indien het geconfigureerde webhook-endpoint met een 2xx responscode antwoordt, wordt er een succesmelding weergegeven
   • Indien het geconfigureerde webhook-endpoint met een andere responscode dan 2xx antwoordt, wordt er een foutmelding weergegeven.

Webhook API

Dit gedeelte beschrijft het webhook-eindpunt voor het ontvangen van testresultaten van axe DevTools.

Eindpuntinformatie

URL-structuur

De URL-structuur bepaalt u grotendeels zelf. U kunt elk gewenst domein en URL-pad gebruiken (zorg ervoor dat u bij het configureren van de aangepaste integratie de juiste URL invoert).

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

Authenticatie

Authenticatie gebeurt met webhook-signaturen. Elk webhook-verzoek bevat een signature header die moet worden geverifieerd om te bevestigen dat het verzoek afkomstig is van axe DevTools.

Signatuurverificatie

1. Er wordt een geheime sleutel gedeeld tussen axe DevTools en uw dienst.
2. De handtekening is opgenomen in de X-Hub-Signature header
3. Formaat: X-Hub-Signature: sha256=<signature>
4. Tijdstempel X-Deque-Request-Timestamp: <ISO timestamp>
5. Verifieer de handtekening door een SHA-256 HMAC te berekenen van de tijdstempel en de body van het verzoek met uw oorspronkelijk verstrekte geheime sleutel.

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

Verzoekkopteksten

Schema van de Request Body

De webhook-payload volgt het axe Universal JSON-formaat(devtools-server/common-export-format). Hieronder vindt u het gedetailleerde schema met voorbeelden:

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

Reactievereisten

Uw webhook-eindpunt moet:

• binnen 10 seconden reageren
• Retourneer een 2xx statuscode voor succesvolle ontvangst

Foutafhandeling

Implementeer geschikte foutafhandeling door in de volgende scenario's een andere statuscode dan 2xx te retourneren:

• Ongeldige signatuur
• Aanvraag time-out
• Onjuist gevormde payloads
• Serverfouten