Intégration personnalisée

L'intégration personnalisée permet aux équipes d'envoyer facilement des données de test entières depuis l'extension axe DevTools directement vers un point de terminaison webhook configurable. Cela vous permet de configurer un point de terminaison webhook personnalisé qui peut consommer des données de test axe DevTools.

Comment ça marche

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. Indiquez un nom (255 caractères maximum)
5. Fournissez votre URL webhook
6. Fournissez un secret (voir authentification ci-dessous)

Envoi des résultats des tests

Définition automatique des paramètres testId et url de requête

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

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

1. Accédez à /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. L'extension axe DevTools récupérera automatiquement le testId et mettra en file d'attente les tests à effectuer
   • Si un paramètre de requête est fourni, le navigateur sera dirigé vers ladite URL url
   • Si aucun paramètre de requête n'est fourni, il vous sera demandé de naviguer manuellement vers l'URL url
3. Ouvrez l'extension axe DevTools si elle n'est pas déjà ouverte
4. Choisissez « Numérisation de page complète », « Numérisation de page partielle » ou n'importe quel IGT pour commencer le test
5. Une fois le test terminé, accédez à l'onglet « Aperçu » de votre test enregistré
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 du webhook configuré répond avec un 2xx code de réponse, un message de réussite sera affiché
   • Si le point de terminaison du webhook configuré répond avec un code de réponse autre que 2xx, un message d'erreur sera affiché

Ajout manuel d'un ID de test

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

API du webhook

Cette section décrit le point de terminaison du webhook pour recevoir les résultats des tests d'axe DevTools.

Informations sur le point final

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 de saisir l'URL correcte lors de la configuration de l'intégration personnalisée).

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

Authentification

L'authentification est implémentée à l'aide de signatures webhook. Chaque demande de webhook inclut un en-tête de signature qui doit être vérifié pour garantir que la demande provient d'axe DevTools.

Vérification de la signature

1. Une clé secrète est partagée entre d'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 à l'aide de votre clé secrète qui a été fournie à l'origine

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

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 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 de webhook doit :

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

Gestion des erreurs

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

• Signature invalide
• Délai d'expiration de la demande
• Charges utiles malformées
• Erreurs de serveur