Intégration personnalisée

L'intégration personnalisée permet aux équipes d'envoyer facilement toutes les données de test de l'extension axe DevTools directement vers un point de terminaison webhook configurable. Cela vous permet de mettre en place un point de terminaison webhook personnalisé qui peut consommer les données de test axe DevTools.

Comment cela fonctionne

Configuration de l'intégration

Tout administrateur du portail de compte axe peut configurer l'intégration.

1. Cliquez sur « CONFIGURATION » dans la barre de navigation
2. Sélectionnez l'onglet « Intégrations »
3. Cliquez sur « Ajouter une nouvelle connexion à l'intégration personnalisée »
4. Fournissez un nom (caractères max : 255)
5. Fournissez l'URL de votre webhook
6. Fournissez un secret (voir authentification ci-dessous)

Envoi des résultats de test

Paramétrage automatique des paramètres de requête testId et url

Pour la configuration automatique des tests, deux paramètres de requête sont pris en charge :

• testId : l'identifiant du test dans votre application interne (par exemple, 1234567)
• url : l'URL de test encodée en URI (par exemple, https%3A%2F%2Fworkshop.dequelabs.com)

1. Lien (ou naviguez dans votre navigateur) vers /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. L'extension axe DevTools détectera automatiquement le testId et programmera le test à effectuer
   • Si un paramètre de requête url est fourni, le navigateur sera dirigé vers cette URL
   • Si aucun paramètre de requête url n'est fourni, il vous sera demandé de naviguer manuellement vers l'URL
3. Ouvrez l'extension axe DevTools si elle n'est pas déjà ouverte
4. Choisissez « Analyse complète de la page », « Analyse partielle de la page » ou tout autre IGT pour commencer le test
5. Une fois le test terminé, accédez à l'onglet « Aperçu » de votre test sauvegardé
6. Ouvrez le menu « Options de partage »
7. Cliquez sur l'option « Envoyer les résultats à l'intégration personnalisée »
   • Si le point de terminaison webhook configuré répond avec un code de réponse 2xx, un message de succès sera affiché
   • Si le point de terminaison webhook configuré répond avec un code de réponse non 2xx, un message d'erreur sera affiché

Ajout manuel de l'ID de test

1. Ouvrez l'extension axe DevTools
2. Créez un nouveau test sauvegardé ou accédez à un test existant
3. Une fois le test terminé, accédez à l'onglet « Aperçu » de votre test sauvegardé
4. Ouvrez le menu « Options de partage »
5. Cliquez sur l'option « Envoyer les résultats à l'intégration personnalisée »
6. Entrez votre ID de test
7. Cliquez sur « Envoyer »
   • Si le point de terminaison webhook configuré répond avec un code de réponse 2xx, un message de succès sera affiché
   • Si le point de terminaison webhook configuré répond avec un code de réponse non 2xx, un message d'erreur sera affiché

API Webhook

Cette section décrit le point de terminaison webhook pour recevoir les résultats de test de axe DevTools.

Informations sur le point de terminaison

Structure de l'URL

La structure de l'URL dépend principalement de vous. Vous pouvez utiliser le domaine et le chemin d'URL de votre choix (assurez-vous simplement d'entrer l'URL correcte lors de la configuration de l'intégration personnalisée).

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

Authentification

L'authentification est mise en œuvre à l'aide de signatures de webhook. Chaque requête de webhook inclut un en-tête de signature qui doit être vérifié pour garantir que la requête provient de axe DevTools.

Vérification de la signature

1. Une clé secrète est partagée entre axe DevTools et votre service
2. La signature est incluse dans l'en-tête X-Hub-Signature
3. Format : X-Hub-Signature: sha256=<signature>
4. Horodatage X-Deque-Request-Timestamp: <ISO timestamp>
5. Vérifiez la signature en calculant un HMAC SHA-256 de l'horodatage et du corps de la requête en utilisant votre clé secrète qui a été initialement fournie

Exemple de vérification de signature (nœud) :

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

En-têtes de requête

Schéma du corps de la requête

La charge utile du webhook suit le format JSON universel axe. Ci-dessous se trouve le schéma détaillé avec des exemples :

Exemple de charge utile

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

Exigences de réponse

Votre point de terminaison webhook doit :

• répondre dans les 10 secondes
• Retourner un code d'état 2xx pour une réception réussie

Gestion des erreurs

Implémentez une gestion appropriée des erreurs en retournant un code d'état non-2xx pour ces scénarios :

• Signature invalide
• Délai d'attente de la requête
• Charges utiles malformées
• Erreurs de serveur