Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Invocar al DevOps agente a través de Webhook
<a name="configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook"></a>

Los webhooks permiten que los sistemas externos AWS DevOps activen automáticamente las investigaciones de los agentes. Esto permite la integración con sistemas de emisión de tickets, herramientas de monitoreo y otras plataformas que pueden enviar solicitudes HTTP cuando se producen incidentes.

## Requisitos previos
<a name="prerequisites"></a>

Antes de configurar el acceso a los webhooks, asegúrate de tener:
+ Un espacio de agente configurado en AWS DevOps Agent
+ Acceso a la consola del AWS DevOps agente
+ El sistema externo que enviará las solicitudes de webhook

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

AWS DevOps El agente admite los siguientes tipos de webhooks:
+ **Integration-specific webhooks**: se generan automáticamente al configurar integraciones de terceros, como Dynatrace, Splunk, Datadog, New Relic o Slack. ServiceNow Estos webhooks están asociados a la integración específica y utilizan métodos de autenticación determinados por el tipo de integración
+ **Webhooks genéricos**: se pueden crear manualmente para iniciar investigaciones desde cualquier fuente que no esté incluida en una integración específica. Los webhooks genéricos utilizan actualmente la autenticación **HMAC** (el token portador no está disponible actualmente).
+ **Webhooks de alertas de Grafana:** Grafana puede enviar notificaciones de alerta directamente al AWS DevOps agente a través de los puntos de contacto de webhook. Para obtener instrucciones de configuración que incluyen una plantilla de notificación personalizada, consulte [Conectar Grafana](connecting-telemetry-sources-connecting-grafana.md).

## Métodos de autenticación de Webhook
<a name="webhook-authentication-methods"></a>

El método de autenticación de tu webhook depende de la integración a la que esté asociado:

**Autenticación HMAC**: utilizada por:
+ Webhooks de integración con Dynatrace
+ Webhooks genéricos (no vinculados a una integración específica de terceros)

**Autenticación mediante token de portador**: utilizada por:
+ Webhooks de integración con Splunk
+ Webhooks de integración de Datadog
+ Webhooks de integración de New Relic
+ ServiceNow webhooks de integración
+ Webhooks de integración de Slack
+ Webhooks de integración de Grafana

### Comprensión de la autenticación HMAC
<a name="understanding-hmac-authentication"></a>

El HMAC (código de autenticación de Hash-based mensajes) es un mecanismo criptográfico que verifica tanto la integridad como la autenticidad de una solicitud de webhook. Cuando envías un webhook con autenticación HMAC, generas una firma mezclando la marca temporal y la carga útil de la solicitud utilizando tu clave secreta con el algoritmo. SHA-256 AWS DevOps El agente calcula de forma independiente el mismo hash por su lado y compara las dos firmas. Si coinciden, se acepta la solicitud.

Como la marca de tiempo está incluida en la firma, el HMAC también ofrece protección contra la reproducción: el AWS DevOps agente puede rechazar las solicitudes con marcas de tiempo demasiado antiguas, lo que impide que un atacante capture y reenvíe una solicitud válida.

### Elegir entre el HMAC y el token Bearer
<a name="choosing-between-hmac-and-bearer-token"></a>


| Consideración | HMAC | Token de portador | 
| --- | --- | --- | 
| Complejidad de la configuración | Más complejo: su cliente debe calcular una firma para cada solicitud utilizando la marca de tiempo y la carga útil | Más sencillo: incluye un token estático en el encabezado Authorization | 
| Integridad de la carga útil | Verificado: cualquier modificación de la carga útil después de la firma invalida la firma | No verificado: el token autentica al remitente pero no protege el contenido de la carga | 
| Protección de reproducción | Built-in — la marca de tiempo de la firma permite al servidor rechazar solicitudes obsoletas | No está integrado: un token capturado se puede reutilizar hasta que se rote | 
| Riesgo de exposición secreta | Inferior: el secreto nunca se transmite en la solicitud; solo se envía la firma computada | Más alto: el token se envía en el encabezado de cada solicitud, lo que aumenta la exposición si se intercepta el tráfico | 
| Cuándo se debe usar | Se recomienda cuando se necesitan garantías de seguridad más sólidas, como en el caso de webhooks genéricos o entornos con requisitos de cumplimiento estrictos | Adecuado cuando la facilidad de integración es una prioridad y se confía en el transporte de su red, como en el caso de las integraciones SaaS gestionadas a través de HTTPS | 

**Nota:** El método de autenticación viene determinado por el tipo de integración. Integration-specific Los webhooks (Splunk, Datadog, New Relic, ServiceNow Slack, Grafana) utilizan la autenticación con token de portador. Dynatrace y los webhooks genéricos utilizan la autenticación HMAC. No puedes cambiar el método de autenticación de un webhook específico de la integración.

## Configurar el acceso al webhook
<a name="configuring-webhook-access"></a>

### Paso 1: Navegue hasta la configuración del webhook
<a name="step-1-navigate-to-the-webhook-configuration"></a>

1. Inicie sesión en la consola AWS de administración y navegue hasta la consola del AWS DevOps agente

1. Seleccione su espacio de agente

1. Ve a la pestaña **Capacidades**

1. **En la sección **Webhook**, haga clic en Configurar**

### Paso 2: Generar las credenciales del webhook
<a name="step-2-generate-webhook-credentials"></a>

**Para webhooks específicos de la integración:**

Los webhooks se generan automáticamente al completar la configuración de una integración de terceros. La URL y las credenciales del punto final del webhook se proporcionan al final del proceso de configuración de la integración.

**Para webhooks genéricos:**

1. Haz clic en **Generar webhook**

1. El sistema generará un key pair HMAC

1. Guarde de forma segura la clave y el secreto generados; no podrá volver a recuperarlos

1. Copia la URL del punto final del webhook proporcionada

### Paso 3: Configura tu sistema externo
<a name="step-3-configure-your-external-system"></a>

Utilice la URL y las credenciales del punto de conexión del webhook para configurar su sistema externo y enviar solicitudes al AWS DevOps agente. Los pasos de configuración específicos dependen del sistema externo.

## Administrar las credenciales de webhook
<a name="managing-webhook-credentials"></a>

**Eliminar credenciales****: para eliminar las credenciales del webhook, vaya a la sección de configuración del webhook y haga clic en Eliminar.** Tras eliminar las credenciales, el punto final del webhook ya no aceptará solicitudes hasta que generes nuevas credenciales.

**Regeneración de credenciales**: para generar nuevas credenciales, elimine primero las credenciales existentes y, a continuación, genere un nuevo key pair o token.

## Uso del webhook
<a name="using-the-webhook"></a>

### Formato de solicitud de webhook
<a name="webhook-request-format"></a>

Para iniciar una investigación, tu sistema externo debe enviar una solicitud HTTP POST a la URL del punto final del webhook.

**Para la versión 1 (autenticación HMAC):**

Encabezados:
+ `Content-Type: application/json`
+ `x-amzn-event-signature: <HMAC signature>`
+ `x-amzn-event-timestamp: <+%Y-%m-%dT%H:%M:%S.000Z>`

La firma HMAC se genera al firmar el cuerpo de la solicitud con su clave secreta mediante. SHA-256

**Para la versión 2 (autenticación con token de portador):**

Encabezados:
+ `Content-Type: application/json`
+ `Authorization: Bearer <your-token>`

**Cuerpo de la solicitud:**

El organismo solicitante debe incluir información sobre el 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 ejemplo
<a name="example-code"></a>

**Versión 1 (autenticación 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);
});
```

**Versión 1 (autenticación 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"
```

**Versión 2 (autenticación con 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),
  });
}
```

**Versión 2 (autenticación 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"
```

## Solución de problemas de webhooks
<a name="troubleshooting-webhooks"></a>

### Si no recibes un 200
<a name="if-you-do-not-receive-a-200"></a>

Un 200 y un mensaje como el webhook recibido indican que la autenticación se ha aprobado y que el mensaje se ha puesto en cola para que el sistema lo verifique y procese. Si no obtienes un 200 sino un 4xx, lo más probable es que haya algún problema con la autenticación o los encabezados. Intenta enviarlo manualmente usando las opciones curl para ayudar a depurar la autenticación.

### Si recibes un 200 pero no se inicia una investigación
<a name="if-you-receive-a-200-but-an-investigation-does-not-start"></a>

La causa probable es una carga mal formateada.

1. Compruebe que tanto la marca de tiempo como el identificador del incidente estén actualizados y sean únicos. Los mensajes duplicados se deduplican.

1. Comprueba que el mensaje sea un JSON válido

1. Comprueba que el formato es correcto

### Si recibes un 200$ y la investigación se cancela inmediatamente
<a name="if-you-receive-a-200-and-investigation-is-immediately-cancelled"></a>

Lo más probable es que hayas alcanzado el límite del mes. Hable con su AWS contacto para solicitar un cambio en el límite de la tarifa, si es necesario.

## Temas relacionados
<a name="related-topics"></a>
+ [Creación de un espacio de agentes](getting-started-with-aws-devops-agent-creating-an-agent-space.md)
+ [¿Qué es una aplicación web para DevOps agentes?](about-aws-devops-agent-what-is-a-devops-agent-web-app.md)
+ [DevOps Permisos de IAM para agentes](aws-devops-agent-security-devops-agent-iam-permissions.md)