Integração personalizada

A integração personalizada permite às equipas enviar facilmente todos os dados de teste da extensão axe DevTools diretamente para um endpoint de webhook configurável. Isto permite implementar um endpoint de webhook personalizado capaz de consumir dados de teste do axe DevTools.

Como funciona

Configuração da integração

Qualquer administrador do axe Account Portal pode configurar a integração.

1. Clique em "CONFIGURAÇÃO" na barra de navegação.
2. Selecione o separador "Integrações"
3. Clique em "Adicionar nova ligação à Integração Personalizada"
4. Introduza um nome (máximo de 255 caracteres)
5. Forneça o URL do webhook
6. Introduza um segredo (consulte autenticação abaixo)

Envio de resultados de testes

Atribuição automática dos parâmetros de consulta testId e url

Para configuração automática de teste, dois parâmetros de consulta são suportados:

• testId: O identificador do teste na sua aplicação interna (por exemplo, 1234567).
• url: URL de teste codificada como URI (por exemplo, https%3A%2F%2Fworkshop.dequelabs.com).

1. Aceda (ou navegue para) /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. A extensão axe DevTools reconhecerá automaticamente o testId e colocará os testes em fila para execução.
   • Se for fornecido um parâmetro de consulta url, o navegador será direcionado para esse URL.
   • Se não for fornecido o parâmetro de consulta url, ser-lhe-á solicitado que navegue manualmente para o URL
3. Abra a extensão axe DevTools se ainda não estiver aberta. Captura de ecrã da página inicial de teste da extensão de integração personalizada conectada(images/custom-integration-connected.png)
4. Você deve selecionar "Full Page Scan", "Partial Page Scan" ou qualquer IGT para iniciar os testes.
5. Após a conclusão do teste, navegue até à aba "Visão geral" do seu teste guardado.
6. Abra o menu "Opções de partilha". Captura do ecrã da opção de menu "Enviar resultados para integração personalizada"(images/custom-integration-send-button.png)
7. Clique na opção "Enviar resultados para integração personalizada" Captura de ecrã do envio bem sucedido da integração personalizada(images/custom-integration-send-success.png)
   • Se o endpoint do webhook configurado responder com o código de resposta 2xx, uma mensagem de sucesso será apresentada.
   • Se o endpoint do webhook configurado responder com um código de resposta diferente de 2xx, uma mensagem de erro será exibida.

Adicionar manualmente o ID do teste

1. Abra a axe DevTools Extension
2. Crie um novo teste guardado ou navegue até um já existente
3. Após a conclusão do teste, navegue até à aba "Visão geral" do seu teste guardado.
4. Abra o menu "Opções de partilha".
5. Clique na opção "Enviar resultados para integração personalizada" Captura do ecrã da opção de menu "Enviar resultados para integração personalizada"(images/custom-integration-send-button.png)
6. Introduza o seu ID de teste
7. Clique em "Enviar"
   • Se o endpoint do webhook configurado responder com o código de resposta 2xx, uma mensagem de sucesso será apresentada.
   • Se o endpoint do webhook configurado responder com um código de resposta diferente de 2xx, uma mensagem de erro será exibida.

API de Webhook

Esta secção descreve o endpoint do webhook para receber resultados de teste do axe DevTools.

Informações do endpoint

Estrutura de URL

A estrutura da URL fica principalmente ao critério do utilizador. Pode utilizar qualquer domínio e caminho de URL que preferir (apenas certifique-se de inserir o URL correto ao configurar a integração personalizada).

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

Autenticação

A autenticação é implementada usando assinaturas de webhook. Cada solicitação de webhook inclui um cabeçalho de assinatura que deve ser validado para garantir que a solicitação tem origem no axe DevTools.

Verificação de Assinatura

1. Uma chave secreta é partilhada entre o axe DevTools e o seu serviço
2. A assinatura está incluída no cabeçalho X-Hub-Signature
3. Formato: X-Hub-Signature: sha256=<signature>
4. Carimbo de data/hora X-Deque-Request-Timestamp: <ISO timestamp>
5. Verifique a assinatura calculando um HMAC SHA-256 do timestamp e do corpo da solicitação usando a chave secreta que lhe foi originalmente fornecida.

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

Cabeçalhos de solicitação

Esquema do Corpo da Solicitação

A carga útil do webhook segue o formato axe Universal JSON format (devtools-server/common-export-format). Abaixo está o esquema detalhado com exemplos:

Exemplo 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 resposta

O endpoint do webhook deve:

• Responda dentro de 10 segundos.
• Retorne um código de estado 2xx para indicar recebimento bem-sucedido.

Tratamento de erros

Implemente um tratamento de erros apropriado, retornando um código de estado diferente de 2xx para estes cenários:

• Assinatura inválida.
• Tempo limite da requisição.
• Payloads malformados.
• Erros do servidor.