Aangepaste Integratie

De aangepaste integratie stelt teams in staat om eenvoudig volledige testgegevens van de axe DevTools-extensie rechtstreeks naar een configureerbare webhook-eindpunt te sturen. Dit stelt u in staat om een aangepast webhook-eindpunt op te zetten dat de testgegevens van axe DevTools kan verwerken.

Hoe het werkt

De Integratie Configureren

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

1. Klik op „CONFIGURATIE“ in de navigatiebalk
2. Selecteer het tabblad „Integraties“
3. Klik op „Nieuwe verbinding toevoegen aan Aangepaste Integratie“
4. Geef een naam op (maximaal aantal tekens: 255)
5. Voer uw webhook-URL in
6. Geef een geheim op (zie authenticatie hieronder)

Testresultaten Verzenden

Automatisch testId en url Query Parameters Instellen

Voor automatische testopstelling worden twee query parameters ondersteund:

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

1. Link (of navigeer uw browser) naar /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. De axe DevTools-extensie pikt automatisch de testId op en zal de test in de wachtrij plaatsen om uitgevoerd te worden
   • Als een url query parameter wordt opgegeven, zal de browser naar de genoemde URL navigeren
   • Als er geen url query parameter wordt opgegeven, wordt u gevraagd om handmatig naar de URL te navigeren
3. Open de axe DevTools-extensie als deze nog niet geopend is
4. Kies "Volledige Pagina Scan", "Gedeeltelijke Pagina Scan" of een andere IGT om met testen te beginnen
5. Zodra het testen is voltooid, navigeer naar het tabblad „Overzicht“ van uw opgeslagen test
6. Open het menu „Delen Opties“
7. Klik op de optie „Resultaten verzenden naar aangepaste integratie“
   • Als het geconfigureerde webhook-eindpunt een 2xx-reactiecode teruggeeft, wordt er een succesvol bericht weergegeven
   • Als het geconfigureerde webhook-eindpunt een andere reactiecode dan 2xx teruggeeft, wordt er een foutmelding weergegeven

Test ID Handmatig Toevoegen

1. Open de axe DevTools-extensie
2. Maak een nieuwe opgeslagen test of navigeer naar een bestaande
3. Zodra het testen is voltooid, navigeer naar het tabblad „Overzicht“ van uw opgeslagen test
4. Open het menu „Delen Opties“
5. Klik op de optie „Resultaten verzenden naar aangepaste integratie“
6. Voer uw Test ID in
7. Klik op „Verzenden“
   • Als het geconfigureerde webhook-eindpunt een 2xx-reactiecode teruggeeft, wordt er een succesvol bericht weergegeven
   • Als het geconfigureerde webhook-eindpunt een andere reactiecode dan 2xx teruggeeft, wordt er een foutmelding weergegeven

Webhook API

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

Eindpunt Informatie

URL-structuur

De URL-structuur is grotendeels aan jou. Je kunt elk gewenst domein en URL-pad gebruiken (zorg er alleen voor dat je de juiste URL invoert bij het configureren van de aangepaste integratie).

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

Authenticatie

Authenticatie wordt geïmplementeerd met behulp van webhook-handtekeningen. Elke webhook-verzoek bevat een handtekeningheader die moet worden geverifieerd om ervoor te zorgen dat het verzoek van axe DevTools afkomstig is.

Handtekeningverificatie

1. Een geheime sleutel wordt gedeeld tussen axe DevTools en jouw service
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 van de tijdstempel en het aanvraaglichaam te berekenen met behulp van je geheime sleutel die oorspronkelijk is verstrekt

Voorbeeld van handtekeningverificatie (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)
  )
}

Verzoek Headers

Aanvraaglichaam Schema

De webhook-payload volgt het axe Universeel JSON-formaat. Hieronder staat 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

Jouw webhook-endpoint moet:

• binnen 10 seconden reageren
• Een 2xx statuscode retourneren voor succesvolle ontvangst

Foutafhandeling

Implementeer passende foutafhandeling door een niet-2xx statuscode te retourneren voor de volgende situaties:

• Ongeldige handtekening
• Verzoek time-out
• Onjuiste payloads
• Serverfouten