Integração Personalizada

A integração personalizada permite que as equipes enviem facilmente todos os dados de teste da extensão axe DevTools diretamente para um endpoint de webhook configurável. Isso permite que você estabeleça um endpoint de webhook personalizado que possa consumir dados de teste do axe DevTools.

Como funciona

Configurando a Integração

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

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

Enviando Resultados de Teste

Definindo Automaticamente os Parâmetros de Consulta testId e url

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

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

1. Link (ou navegue seu navegador) para /axe-devtools/test-setup?testId=1234567&url=https%3A%2F%2Fworkshop.dequelabs.com
2. A extensão axe DevTools detectará automaticamente o testId e colocará em fila o teste a ser realizado
   • Se um parâmetro de consulta url for fornecido, o navegador será direcionado para a URL informada
   • Se nenhum parâmetro de consulta url for fornecido, será solicitado que você navegue manualmente para a URL
3. Abra a extensão axe DevTools se ainda não estiver aberta
4. Escolha "Escaneamento Completo da Página", "Escaneamento Parcial da Página" ou qualquer IGT para começar a testar
5. Uma vez concluído o teste, navegue para a aba "Visão Geral" do seu teste salvo
6. Abra o menu "Opções de Compartilhamento"
7. Clique na opção "Enviar resultados para integração personalizada"
   • Se o endpoint de webhook configurado responder com um código de resposta 2xx, uma mensagem de sucesso será exibida
   • Se o endpoint de webhook configurado responder com um código de resposta diferente de 2xx, uma mensagem de erro será exibida

Adicionando Manualmente o ID do Teste

1. Abra a extensão axe DevTools
2. Crie um novo teste salvo ou navegue para um existente
3. Uma vez concluído o teste, navegue para a aba "Visão Geral" do seu teste salvo
4. Abra o menu "Opções de Compartilhamento"
5. Clique na opção "Enviar resultados para integração personalizada"
6. Insira seu ID de Teste
7. Clique em "Enviar"
   • Se o endpoint de webhook configurado responder com um código de resposta 2xx, uma mensagem de sucesso será exibida
   • Se o endpoint de webhook configurado responder com um código de resposta diferente de 2xx, uma mensagem de erro será exibida

API de Webhook

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

Informações do Endpoint

Estrutura da URL

A estrutura do URL é majoritariamente de sua escolha. Você pode usar o domínio e o 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 verificado para garantir que a solicitação veio do axe DevTools.

Verificação de Assinatura

1. Uma chave secreta é compartilhada entre o axe DevTools e seu serviço
2. A assinatura é incluída no cabeçalho X-Hub-Signature
3. Formato: X-Hub-Signature: sha256=<signature>
4. Timestamp 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 sua chave secreta que foi fornecida originalmente

Exemplo de verificação de assinatura (nó):

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 da Solicitação

Esquema do Corpo da Solicitação

O payload do webhook segue o formato JSON Universal do axe. Abaixo está o esquema detalhado com exemplos:

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

Seu endpoint de webhook deve:

• responder dentro de 10 segundos
• Retornar um código de status 2xx para recebimento bem-sucedido

Tratamento de Erros

Implemente um tratamento de erro apropriado retornando um código de status não 2xx para os seguintes cenários:

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