As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Invocando o DevOps agente por meio do Webhook

Os webhooks permitem que sistemas externos acionem automaticamente as investigações do AWS DevOps agente. Isso permite a integração com sistemas de emissão de tíquetes, ferramentas de monitoramento e outras plataformas que podem enviar solicitações HTTP quando ocorrem incidentes.

Pré-requisitos

Antes de configurar o acesso ao webhook, verifique se você tem:

Tipos de webhook

AWS DevOps O agente oferece suporte aos seguintes tipos de webhooks:

Métodos de autenticação de webhook

O método de autenticação do seu webhook depende da integração à qual ele está associado:

Autenticação HMAC — Usada por:

Autenticação por token de portador — Usada por:

Entendendo a autenticação HMAC

O HMAC (Hash-based Message Authentication Code) é um mecanismo criptográfico que verifica a integridade e a autenticidade de uma solicitação de webhook. Ao enviar um webhook com autenticação HMAC, você gera uma assinatura combinando o carimbo de data/hora e a carga útil da solicitação usando sua chave secreta com o algoritmo. SHA-256 AWS DevOps O agente calcula de forma independente o mesmo hash e compara as duas assinaturas. Se corresponderem, a solicitação será aceita.

Como o carimbo de data/hora está incluído na assinatura, o HMAC também oferece proteção contra repetição — o AWS DevOps agente pode rejeitar solicitações com carimbos de data/hora que estão muito distantes, impedindo que um invasor capture e reenvie uma solicitação válida.

Escolhendo entre o HMAC e o token Bearer

Configurando o acesso ao webhook

Etapa 1: Navegue até a configuração do webhook

Etapa 2: gerar credenciais de webhook

Para webhooks específicos de integração:

Os webhooks são gerados automaticamente quando você conclui a configuração de uma integração de terceiros. O URL e as credenciais do endpoint do webhook são fornecidos no final do processo de configuração da integração.

Para webhooks genéricos:

Etapa 3: configurar seu sistema externo

Use a URL e as credenciais do endpoint do webhook para configurar seu sistema externo para enviar solicitações ao Agente. AWS DevOps As etapas de configuração específicas dependem do seu sistema externo.

Gerenciando credenciais de webhook

As credenciais do webhook são confidenciais. AWS DevOps O agente mostra o segredo do webhook uma vez, quando você cria o webhook. Ele não retorna o segredo novamente por meio do console, da API ou da infraestrutura como código. O URL do webhook permanece disponível. Se você perder o segredo ou criar o webhook sem gravá-lo, gire o webhook para gerar um novo segredo.

Credenciais rotativas de webhook

Você pode alternar as credenciais de qualquer webhook na guia Capacidades. O Rotation mantém o mesmo URL do webhook e gera um novo segredo. A rotação invalida o segredo anterior, então o remetente pára até que você o atualize com o novo segredo. Gire um webhook quando perder o segredo ou quando quiser substituir um segredo que possa estar comprometido.

Para girar um webhook:

Para copiar o URL do webhook sem girar o segredo, escolha Copiar URL.

Webhooks criados com infraestrutura como código

Quando você cria um webhook com AWS CloudFormation o AWS CDK ou o Terraform, a pilha não retorna o segredo do webhook como saída, porque é um valor confidencial. Após a conclusão da implantação, obtenha o segredo girando o webhook, conforme descrito na seção anterior. Em seguida, configure seu serviço de terceiros com o URL do webhook e o novo segredo.

Removendo credenciais de webhook

Para excluir um webhook genérico, abra a seção Webhook do Agent Space, escolha Ações e escolha Remover. Depois de remover o webhook, o endpoint não aceita mais solicitações até que você crie um novo webhook.

Usando o webhook

Formato de solicitação de webhook

Para iniciar uma investigação, seu sistema externo deve enviar uma solicitação HTTP POST para a URL do endpoint do webhook.

Para a versão 1 (autenticação HMAC):

Cabeçalhos:

A assinatura HMAC é gerada assinando o corpo da solicitação com sua chave secreta usando SHA-256.

Para a versão 2 (autenticação por token de portador):

Cabeçalhos:

Corpo da solicitação:

O corpo da solicitação deve incluir informações sobre o incidente:

{
  "eventType": "incident",
  "incidentId": "incident-123",
  "action": "created",
  "priority": "HIGH",
  "title": "High CPU usage on production server",
  "description": "High CPU usage on production server host ABC in AWS account 1234 region us-east-1",
  "timestamp": "2025-11-23T18:00:00Z",
  "service": "MyProductionService",
  "data": {
    "metadata": {
      "region": "us-east-1",
      "environment": "production"
    }
  }
}

Esquema de carga útil:

{
    eventType: 'incident';
    incidentId: string;
    action: 'created' | 'updated' | 'closed' | 'resolved';
    priority: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "MINIMAL";
    title: string;
    description?: string;
    timestamp?: string;
    service?: string;
    // The original event generated by service is attached here.
    data?: object;
}

Código de exemplo

Versão 1 (autenticação HMAC) -: JavaScript

const crypto = require('crypto');

// Webhook configuration
const webhookUrl = 'https://your-webhook-endpoint.amazonaws.com/invoke';
const webhookSecret = 'your-webhook-secret-key';

// Incident data
const incidentData = {  
    eventType: 'incident',
    incidentId: 'incident-123',
    action: 'created',
    priority: "HIGH",
    title: 'High CPU usage on production server',
    description: 'High CPU usage on production server host ABC in AWS account 1234 region us-east-1',
    timestamp: new Date().toISOString(),
    service: 'MyTestService',
    data: {
      metadata: {
        region: 'us-east-1',
        environment: 'production'
      }
    }
};

// Convert data to JSON string
const payload = JSON.stringify(incidentData);
const timestamp = new Date().toISOString();
const hmac = crypto.createHmac("sha256", webhookSecret);
hmac.update(`${timestamp}:${payload}`, "utf8");
const signature = hmac.digest("base64");

// Send the request
fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-amzn-event-timestamp': timestamp,
    'x-amzn-event-signature': signature
  },
  body: payload
})
.then(res => {
  console.log(`Status Code: ${res.status}`);
  return res.text();
})
.then(data => {
  console.log('Response:', data);
})
.catch(error => {
  console.error('Error:', error);
});

Versão 1 (autenticação HMAC) - cURL:

#!/bin/bash

# Configuration
WEBHOOK_URL="https://event-ai.us-east-1.api.aws/webhook/generic/YOUR_WEBHOOK_ID"
SECRET="YOUR_WEBHOOK_SECRET"

# Create payload
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
INCIDENT_ID="test-alert-$(date +%s)"

PAYLOAD=$(cat <<EOF
{
"eventType": "incident",
"incidentId": "$INCIDENT_ID",
"action": "created",
"priority": "HIGH",
"title": "Test Alert",
"description": "Test alert description",
"service": "TestService",
"timestamp": "$TIMESTAMP"
}
EOF
)

# Generate HMAC signature
SIGNATURE=$(echo -n "${TIMESTAMP}:${PAYLOAD}" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)

# Send webhook
curl -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "x-amzn-event-timestamp: $TIMESTAMP" \
-H "x-amzn-event-signature: $SIGNATURE" \
-d "$PAYLOAD"

Versão 2 (autenticação por token de portador) -: JavaScript

function sendEventToWebhook(webhookUrl, secret) {
  const timestamp = new Date().toISOString();
  
  const payload = {
    eventType: 'incident',
    incidentId: 'incident-123',
    action: 'created',
    priority: "HIGH",
    title: 'Test Alert',
    description: 'Test description',
    timestamp: timestamp,
    service: 'TestService',
    data: {}
  };

  fetch(webhookUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-amzn-event-timestamp": timestamp,
      "Authorization": `Bearer ${secret}`,  // Fixed: template literal
    },
    body: JSON.stringify(payload),
  });
}

Versão 2 (autenticação por token de portador) - cURL:

#!/bin/bash

# Configuration
WEBHOOK_URL="https://event-ai.us-east-1.api.aws/webhook/generic/YOUR_WEBHOOK_ID"
SECRET="YOUR_WEBHOOK_SECRET"

# Create payload
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
INCIDENT_ID="test-alert-$(date +%s)"

PAYLOAD=$(cat <<EOF
{
"eventType": "incident",
"incidentId": "$INCIDENT_ID",
"action": "created",
"priority": "HIGH",
"title": "Test Alert",
"description": "Test alert description",
"service": "TestService",
"timestamp": "$TIMESTAMP"
}
EOF
)

# Send webhook
curl -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "x-amzn-event-timestamp: $TIMESTAMP" \
-H "Authorization: Bearer $SECRET" \
-d "$PAYLOAD"

Solução de problemas de webhooks

Se você não receber um 200

Um 200 e uma mensagem como webhook recebida indicam que a autenticação foi aprovada e a mensagem foi colocada na fila para que o sistema verifique e processe. Se você não obtiver 200, mas 4xx, provavelmente há algo errado com a autenticação ou os cabeçalhos. Tente enviar manualmente usando as opções curl para ajudar a depurar a autenticação.

Se você receber 200, mas uma investigação não começar

A causa provável é uma carga mal formatada.

Se você receber 200 e a investigação for imediatamente cancelada

O mais provável é que você tenha atingido o limite do mês. Fale com seu AWS contato para solicitar uma alteração no limite de tarifa, se apropriado.

Tópicos relacionados