Integrazione personalizzata

L'integrazione personalizzata consente ai team di inviare facilmente tutti i dati dei test dall'estensione axe DevTools direttamente a un endpoint webhook configurabile. Ciò consente di creare un endpoint webhook personalizzato in grado di utilizzare i dati di test axe DevTools.

Come funziona

Configurazione dell'integrazione

Qualsiasi amministratore dell'axe Account Portal può configurare l'integrazione.

1. Fare clic su "CONFIGURAZIONE" nella barra di navigazione
2. Seleziona la scheda "Integrazioni"
3. Fare clic su "Aggiungi nuova connessione all'integrazione personalizzata"
4. Fornisci un nome (caratteri massimi: 255)
5. Fornisci il suo URL webhook
6. Fornire una chiave segreta (vedere autenticazione sotto)

Invio dei risultati dei test

Impostazione automatica dei parametri di query testId e url

Per la configurazione automatica dei test sono supportati due parametri di query:

• testId: l'identificativo del test all'interno della sua applicazione interna (ad esempio 1234567)
• url: l'URL di test codificato URI (es. https%3A%2F%2Fworkshop.dequelabs.com)

1. Collegati (o navighi nel tuo browser) a /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. L'estensione axe DevTools rileverà automaticamente il testId e metterà in coda i test da eseguire
   • Se viene fornito un parametro di query url, il browser verrà indirizzerà a tale URL
   • Se non viene fornito alcun parametro di query url, le verrà chiesto di navigare manualmente verso l'URL
3. Aprire l'estensione axe DevTools se non è già aperta
4. Scegli "Scansione pagina intera", "Scansione pagina parziale" o qualsiasi IGT per iniziare il test
5. Una volta completato il test, vai alla scheda "Panoramica" del test salvato
6. Apri il menu "Opzioni di condivisione"
7. Fare clic sull'opzione "Invia risultati all'integrazione personalizzata"
   • Se l'endpoint del webhook configurato risponde con un codice di risposta 2xx, verrà visualizzato un messaggio di successo
   • Se l'endpoint del webhook configurato risponde con un codice di risposta non 2xx, verrà visualizzato un messaggio di errore

Aggiunta manuale dell'ID del test

1. Apri l'estensione axe DevTools
2. Crea un nuovo test salvato o accedi a uno esistente
3. Una volta completato il test, vai alla scheda "Panoramica" del test salvato
4. Apri il menu "Opzioni di condivisione"
5. Fare clic sull'opzione "Invia risultati all'integrazione personalizzata"
6. Inserisci il tuo ID test
7. Fare clic su "Invia"
   • Se l'endpoint del webhook configurato risponde con un codice di risposta 2xx, verrà visualizzato un messaggio di successo
   • Se l'endpoint del webhook configurato risponde con un codice di risposta non 2xx, verrà visualizzato un messaggio di errore

API del webhook

Questa sezione descrive l'endpoint del webhook per ricevere i risultati dei test da axe DevTools.

Informazioni sull'endpoint

Struttura URL

La struttura dell'URL dipende principalmente da lei. Può utilizzare il dominio e il percorso URL che preferisce (si assicuri solo di inserire l'URL corretto quando configura l'integrazione personalizzata).

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

Autenticazione

L'autenticazione viene implementata tramite firme webhook. Ogni richiesta webhook include un'intestazione di firma che deve essere verificata per garantire che la richiesta provenga da axe DevTools.

Verifica della firma

1. Una chiave segreta è condivisa tra axe DevTools e il suo servizio
2. La firma è inclusa nell'intestazione X-Hub-Signature
3. Formato: X-Hub-Signature: sha256=<signature>
4. Marca temporale X-Deque-Request-Timestamp: <ISO timestamp>
5. Verificare la firma calcolando un HMAC SHA-256 del timestamp e del corpo della richiesta utilizzando la chiave segreta originariamente fornita

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

Intestazioni di richiesta

Schema del corpo della richiesta

Il payload del webhook segue il formato axe Universal JSON. Di seguito lo schema dettagliato con esempi:

Esempio di 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"
    }
  ]
}

Requisiti di risposta

L'endpoint del webhook deve:

• rispondere entro 10 secondi
• Restituisci un codice di stato 2xx per la ricezione avvenuta con successo

Gestione degli errori

Implementare una gestione degli errori appropriata restituendo un codice di stato diverso da 2xx per questi scenari:

• Firma non valida
• Timeout della richiesta
• Payload malformati
• Errori del server