Integrazione Personalizzata

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

Come funziona

Configurazione dell'Integrazione

Qualsiasi amministratore del Portale account axe può configurare l'integrazione.

1. Clicca su "CONFIGURAZIONE" nella barra di navigazione
2. Seleziona la scheda "Integrazioni"
3. Clicca su "Aggiungi nuova connessione all'integrazione personalizzata"
4. Fornisci un nome (max caratteri: 255)
5. Fornisci l'URL del tuo webhook
6. Fornisci un segreto (vedi autenticazione sotto)

Invio dei Risultati del Test

Impostazione Automatica dei Parametri di Query testId e url

Per l'impostazione automatica del test, sono supportati due parametri di query:

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

1. Collega (o naviga il tuo browser) su /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 il test da eseguire
   • Se viene fornito un parametro di query url, il browser verrà indirizzato verso quel URL
   • Se non viene fornito un parametro di query url, ti verrà richiesto di navigare manualmente all'URL
3. Apri l'estensione axe DevTools se non è già aperta
4. Scegli "Scansione Completa della Pagina", "Scansione Parziale della Pagina" o qualsiasi IGT per iniziare il test
5. Una volta completato il test, vai alla scheda "Panoramica" del tuo test salvato
6. Apri il menu "Opzioni di Condivisione"
7. Clicca sull'opzione "Invia risultati all'integrazione personalizzata"
   • Se l'endpoint webhook configurato risponde con un codice di risposta 2xx, verrà visualizzato un messaggio di successo
   • Se l'endpoint webhook configurato risponde con un codice di risposta diverso da 2xx, verrà visualizzato un messaggio di errore

Aggiungere Manualmente il Test ID

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

API del Webhook

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

Informazioni sull'Endpoint

Struttura dell'URL

La struttura dell'URL è per lo più a tuo piacimento. Puoi utilizzare qualsiasi dominio e percorso URL desideri (devi solo assicurarti di inserire l'URL corretto quando configuri l'integrazione personalizzata).

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

Autenticazione

L'autenticazione è implementata utilizzando le firme dei webhook. Ogni richiesta webhook include un'intestazione della firma che deve essere verificata per garantire che la richiesta sia arrivata da axe DevTools.

Verifica della firma

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

Esempio di verifica della firma (nodo):

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 della richiesta

Schema del corpo della richiesta

Il payload del webhook segue il formato JSON universale di axe. Di seguito è riportato 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

Il tuo endpoint webhook deve:

• rispondere entro 10 secondi
• Restituire un codice di stato 2xx per la ricezione riuscita

Gestione degli errori

Implementa una gestione errori appropriata restituendo un codice di stato non-2xx per questi scenari:

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