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
<a name="configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook"></a>

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 bilhetes, ferramentas de monitoramento e outras plataformas que podem enviar solicitações HTTP quando ocorrem incidentes.

## Pré-requisitos
<a name="prerequisites"></a>

Antes de configurar o acesso ao webhook, verifique se você tem:
+ Um Espaço do Agente configurado no AWS DevOps Agente
+ Acesso ao console do AWS DevOps agente
+ O sistema externo que enviará solicitações de webhook

## Tipos de webhook
<a name="webhook-types"></a>

AWS DevOps O Agent oferece suporte aos seguintes tipos de webhooks:
+ **Integration-specific webhooks** — gerados automaticamente quando você configura integrações de terceiros, como Dynatrace, Splunk, Datadog, New Relic ou Slack. ServiceNow Esses webhooks estão associados à integração específica e usam métodos de autenticação determinados pelo tipo de integração.
+ **Webhooks genéricos** — Podem ser criados manualmente para acionar investigações de qualquer fonte não coberta por uma integração específica. Atualmente, os webhooks genéricos usam autenticação **HMAC** (o token do portador não está disponível no momento).
+ **Webhooks de alerta do Grafana** — O Grafana pode enviar notificações de alerta diretamente AWS DevOps ao Agente por meio de pontos de contato do webhook. Para obter instruções de configuração, incluindo um modelo de notificação personalizado, consulte [Conectando o Grafana](connecting-telemetry-sources-connecting-grafana.md).

## Métodos de autenticação de webhook
<a name="webhook-authentication-methods"></a>

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

**Autenticação HMAC** — usada por:
+ Webhooks de integração com o Dynatrace
+ Webhooks genéricos (não vinculados a uma integração específica de terceiros)

**Autenticação de token do portador** — usada por:
+ Webhooks de integração com o Splunk
+ Webhooks de integração com Datadog
+ Webhooks de integração com a New Relic
+ ServiceNow webhooks de integração
+ Webhooks de integração com o Slack
+ Webhooks de integração com Grafana

### Entendendo a autenticação HMAC
<a name="understanding-hmac-authentication"></a>

O HMAC (Código de Autenticação de Hash-based Mensagens) é 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 timestamp e a carga da solicitação usando sua chave secreta com o algoritmo. SHA-256 AWS DevOps O agente calcula de forma independente o mesmo hash em seu lado 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 fornece proteção de repetição — o AWS DevOps agente pode rejeitar solicitações com carimbos de data/hora muito antigos, impedindo que um invasor capture e reenvie uma solicitação válida.

### Escolhendo entre HMAC e token Bearer
<a name="choosing-between-hmac-and-bearer-token"></a>


| Consideração | HMAC | Token do portador | 
| --- | --- | --- | 
| Complexidade da configuração | Mais complexo — seu cliente deve computar uma assinatura para cada solicitação usando o carimbo de data/hora e a carga | Mais simples — inclua um token estático no cabeçalho Authorization | 
| Integridade da carga | Verificado — qualquer modificação na carga após a assinatura invalida a assinatura | Não verificado — o token autentica o remetente, mas não protege o conteúdo da carga | 
| Proteção de repetição | Built-in — o timestamp na assinatura permite que o servidor rejeite solicitações obsoletas | Não incorporado — um token capturado pode ser reutilizado até ser rotacionado | 
| Risco de exposição secreta | Inferior — o segredo nunca é transmitido na solicitação; somente a assinatura computada é enviada | Maior — o token é enviado em cada cabeçalho de solicitação, aumentando a exposição se o tráfego for interceptado | 
| Quando usar | Recomendado quando você precisa de garantias de segurança mais fortes, como para webhooks genéricos ou ambientes com requisitos rígidos de conformidade | Adequado quando a facilidade de integração é uma prioridade e seu transporte de rede é confiável, como para integrações SaaS gerenciadas via HTTPS | 

**Observação:** o método de autenticação é determinado pelo tipo de integração. Integration-specific webhooks (Splunk, Datadog, New Relic, ServiceNow Slack, Grafana) usam autenticação de token de portador. O Dynatrace e os webhooks genéricos usam autenticação HMAC. Você não pode alterar o método de autenticação de um webhook específico da integração.

## Configurando o acesso ao webhook
<a name="configuring-webhook-access"></a>

### Etapa 1: Navegue até a configuração do webhook
<a name="step-1-navigate-to-the-webhook-configuration"></a>

1. Faça login no console AWS de gerenciamento e navegue até o console do AWS DevOps agente

1. Selecione seu espaço de agente

1. Vá para a guia **Capacidades**

1. **Na seção **Webhook**, clique em Configurar**

### Etapa 2: gerar credenciais de webhook
<a name="step-2-generate-webhook-credentials"></a>

**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:**

1. Clique em **Gerar webhook**

1. O sistema gerará um par de chaves HMAC

1. Armazene com segurança a chave e o segredo gerados — você não poderá recuperá-los novamente

1. Copie o URL do endpoint do webhook fornecido

### Etapa 3: configurar seu sistema externo
<a name="step-3-configure-your-external-system"></a>

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

## Gerenciando credenciais de webhook
<a name="managing-webhook-credentials"></a>

**Removendo credenciais** **— Para excluir as credenciais do webhook, acesse a seção de configuração do webhook e clique em Remover.** Depois de remover as credenciais, o endpoint do webhook não aceitará mais solicitações até que você gere novas credenciais.

**Regeneração de credenciais** — Para gerar novas credenciais, primeiro remova as existentes e, em seguida, gere um novo token ou par de chaves.

## Usando o webhook
<a name="using-the-webhook"></a>

### Formato de solicitação de webhook
<a name="webhook-request-format"></a>

Para acionar 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:
+ `Content-Type: application/json`
+ `x-amzn-event-signature: <HMAC signature>`
+ `x-amzn-event-timestamp: <+%Y-%m-%dT%H:%M:%S.000Z>`

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

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

Cabeçalhos:
+ `Content-Type: application/json`
+ `Authorization: Bearer <your-token>`

**Corpo da solicitação:**

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

```
json

{
  "title": "Incident title",
  "severity": "high",
  "affectedResources": ["resource-id-1", "resource-id-2"],
  "timestamp": "2025-11-23T18:00:00Z",
  "description": "Detailed incident description",
  "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
<a name="example-code"></a>

**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 do token do 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 do token do 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 com webhooks
<a name="troubleshooting-webhooks"></a>

### Se você não receber um 200
<a name="if-you-do-not-receive-a-200"></a>

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

### Se você receber um 200, mas a investigação não começar
<a name="if-you-receive-a-200-but-an-investigation-does-not-start"></a>

A causa provável é uma carga com formato incorreto.

1. Verifique se o timestamp e o ID do incidente estão atualizados e exclusivos. As mensagens duplicadas são desduplicadas.

1. Verifique se a mensagem é um JSON válido

1. Verifique se o formato está correto

### Se você receber um 200 e a investigação for imediatamente cancelada
<a name="if-you-receive-a-200-and-investigation-is-immediately-cancelled"></a>

Provavelmente você atingiu o limite do mês. Fale com seu AWS contato para solicitar uma alteração do limite de tarifa, se apropriado.

## Tópicos relacionados
<a name="related-topics"></a>
+ [Criação de um espaço de agente](getting-started-with-aws-devops-agent-creating-an-agent-space.md)
+ [O que é um DevOps Agent Web App?](about-aws-devops-agent-what-is-a-devops-agent-web-app.md)
+ [DevOps Permissões do Agent IAM](aws-devops-agent-security-devops-agent-iam-permissions.md)