Integración personalizada

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

Cómo funciona

Configurando la integración

Cualquier administrador del axe Account Portal 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 la integración personalizada".
4. Proporcione un nombre (máximo de caracteres: 255)
5. Proporcione su URL webhook
6. Proporcione un secreto (ver autenticación a continuación)

Envío de resultados de pruebas

Configuración automática de testId y url parámetros de consulta

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 con URI (por ejemplo, https%3A%2F%2Fworkshop.dequelabs.com)

1. Vaya (o navegue) 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 pondrá en cola las pruebas que se realizarán.
   • Si se proporciona un url parámetro de consulta, el navegador será dirigido a dicha URL.
   • Si no se proporciona ningún url parámetro de consulta, se le pedirá que navegue manualmente a la URL.
3. Abra la extensión axe DevTools si aún no está abierta
4. Seleccione "Escaneo de página completa", "Escaneo de página parcial" o cualquier IGT para comenzar la prueba
5. Una vez completada la prueba, navegue a la pestaña "Descripción general" de su prueba guardada.
6. Abra el menú "Opciones para compartir"
7. Haga clic en la opción "Enviar resultados a integración personalizada".
   • Si el punto final del webhook configurado responde con un código de respuesta 2xx, se mostrará un mensaje de éxito.
   • Si el punto final del webhook configurado responde con un código de no respuesta 2xx, se mostrará un mensaje de error.

Agregar ID de prueba manualmente

1. Abra la extensión axe DevTools
2. Cree una nueva prueba guardada o navegue a una existente
3. Una vez completada la prueba, navegue a la pestaña "Descripción general" de su prueba guardada.
4. Abra el menú "Opciones para 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 punto final del webhook configurado responde con un código de respuesta 2xx, se mostrará un mensaje de éxito.
   • Si el punto final del webhook configurado responde con un código de no respuesta 2xx, se mostrará un mensaje de error.

API del webhook

Esta sección describe el punto final del webhook para recibir los resultados de la prueba de axe DevTools.

Información del punto final

Estructura de URL

La estructura de la URL depende en gran medida de usted. Puede utilizar cualquier dominio y ruta URL que desee (solo asegúrese de ingresar la URL correcta al configurar la integración personalizada).

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

Autenticación

La autenticación se implementa mediante firmas de webhook. Cada solicitud de webhook incluye un encabezado de firma que debe verificarse para garantizar que la solicitud provenga de axe DevTools.

Verificación de firma

1. Se comparte una clave secreta entre axe DevTools y su 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. Verifique la firma calculando un HMAC SHA-256 de la marca de tiempo y el cuerpo de la solicitud utilizando su clave secreta que se proporcionó originalmente

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

Encabezados de solicitud

Esquema del cuerpo de la solicitud

La carga útil del webhook sigue el formato JSON universal axe. A continuación se muestra el esquema detallado con ejemplos:

Ejemplo de carga útil

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

Su punto final de webhook debe:

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

Manejo de errores

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

• Firma inválida
• Tiempo de espera de solicitud
• Cargas útiles malformadas
• Errores del servidor