Integración Personalizada

La integración personalizada permite a los equipos enviar fácilmente todos los datos de prueba desde la extensión axe DevTools directamente a un endpoint configurable de webhook. Esto le permite configurar un endpoint de webhook personalizado que pueda consumir los datos de prueba de axe DevTools.

Cómo funciona

Configuración de la Integración

Cualquier administrador del portal de cuentas de axe puede configurar la integración.

1. Haga clic en „CONFIGURACIÓN“ en la barra de navegación
2. Seleccione la pestaña „Integraciones“
3. Haga clic en „Agregar nueva conexión a Integración Personalizada“
4. Proporcione un nombre (máx. 255 caracteres)
5. Proporcione la URL de su webhook
6. Proporcione un secreto (ver autenticación abajo)

Envío de Resultados de Prueba

Configuración Automática de Parámetros de Consulta testId y url

Para la configuración automática de pruebas, se admiten dos parámetros de consulta:

• testId: el identificador de la prueba dentro de su aplicación interna (por ejemplo, 1234567)
• url: la URL de prueba codificada en URI (por ejemplo, https%3A%2F%2Fworkshop.dequelabs.com)

1. Enlace (o navegue su navegador) a /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. La extensión axe DevTools detectará automáticamente el testId y programará la prueba que se va a realizar
   • Si se proporciona un parámetro de consulta url, el navegador se dirigirá a dicha URL
   • Si no se proporciona un parámetro de consulta url, se le pedirá que navegue manualmente a la URL
3. Abra la extensión axe DevTools si no está ya abierta
4. Elija „Escaneo de Página Completa“, „Escaneo de Página Parcial“ o cualquier IGT para comenzar a probar
5. Una vez que la prueba esté completa, navegue a la pestaña „Vista general“ de su prueba guardada
6. Abra el menú „Opciones de Compartir“
7. Haga clic en la opción „Enviar resultados a integración personalizada“
   • Si el endpoint configurado del webhook responde con un código de respuesta 2xx, se mostrará un mensaje de éxito
   • Si el endpoint configurado del webhook responde con un código de respuesta diferente a 2xx, se mostrará un mensaje de error

Añadir Manualmente el ID de Prueba

1. Abra la extensión axe DevTools
2. Cree una nueva prueba guardada o navegue a una existente
3. Una vez que la prueba esté completa, navegue a la pestaña „Vista general“ de su prueba guardada
4. Abra el menú „Opciones de Compartir“
5. Haga clic en la opción „Enviar resultados a integración personalizada“
6. Ingrese su ID de Prueba
7. Haga clic en „Enviar“
   • Si el endpoint configurado del webhook responde con un código de respuesta 2xx, se mostrará un mensaje de éxito
   • Si el endpoint configurado del webhook responde con un código de respuesta diferente a 2xx, se mostrará un mensaje de error

API de Webhook

Esta sección describe el endpoint de webhook para recibir resultados de prueba de axe DevTools.

Información del Endpoint

Estructura de la URL

La estructura de la URL depende principalmente de ti. Puedes usar el dominio y la ruta de URL que desees (asegúrate de ingresar la URL correcta al configurar la integración personalizada).

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

Autenticación

La autenticación se implementa utilizando firmas de webhook. Cada solicitud de webhook incluye un encabezado de firma que debe verificarse para asegurar que la solicitud proviene de axe DevTools.

Verificación de Firma

1. Se comparte una clave secreta entre axe DevTools y tu servicio
2. La firma está incluida en el encabezado X-Hub-Signature
3. Formato: X-Hub-Signature: sha256=<signature>
4. Marca de tiempo X-Deque-Request-Timestamp: <ISO timestamp>
5. Verifica la firma calculando un HMAC SHA-256 de la marca de tiempo y el cuerpo de la solicitud usando tu clave secreta que fue proporcionada originalmente

Ejemplo de verificación de firma (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)
  )
}

Encabezados de Solicitud

Esquema de Cuerpo de Solicitud

El payload del webhook sigue el formato JSON Universal de axe. A continuación se presenta el esquema detallado con ejemplos:

Ejemplo de 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"
    }
  ]
}

Requisitos de Respuesta

Tu punto final de webhook debe:

• responder dentro de 10 segundos
• Devolver un código de estado 2xx para la recepción exitosa

Manejo de Errores

Implementa un manejo adecuado de errores devolviendo un código de estado no 2xx para estos escenarios:

• Firma inválida
• Tiempo de espera de la solicitud
• Payloads malformados
• Errores del servidor