Usa webhooks de despliegue

Este texto fue traducido usando IA. Si deseas ver el texto original en inglés, haz clic aquí.

Los webhooks de despliegue notifican a una URL externa cuando el estado de tu despliegue de GitHub cambia en WordPress.com. Esta guía explica cómo crear, verificar y gestionar webhooks usando la REST API de WordPress.com.

Necesitas una conexión de despliegue de GitHub activa en tu sitio de WordPress.com antes de poder añadir webhooks. Si aún no has conectado un repositorio, sigue los pasos en Usar despliegues de GitHub en WordPress.com.

También necesitas el ID de tu sitio y el ID de despliegue, que puedes obtener a través de la REST API de WordPress.com.

Los webhooks de despliegue envían solicitudes HTTP POST a una URL que tú elijas cada vez que ocurre un evento de despliegue. Puedes registrar hasta cinco webhooks por conexión de despliegue.

Para crear un webhook:

1. Envía una solicitud POST al endpoint de webhooks:

POST /wpcom/v2/sites/{site_id}/hosting/code-deployments/{deployment_id}/webhooks

2. Incluye los parámetros requeridos en el cuerpo de la solicitud:

• url (requerido): La URL que recibe las solicitudes POST del webhook. Debe usar HTTP o HTTPS.
• events (opcional): Lista de eventos separados por comas a los que suscribirse. Si se omite, se suscribe a todos los eventos de forma predeterminada.

3. Envía la solicitud. A continuación se muestra un ejemplo del cuerpo de la solicitud y la respuesta:

Solicitud:

{
  "url": "https://yourgroovydomain.com/webhook",
  "events": "completed,failed"
}

Respuesta:

{
  "success": true,
  "webhook": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://yourgroovydomain.com/webhook",
    "secret": "abc123def456ghi789jkl012mno345pqr678stu901vwx234",
    "events": ["completed", "failed"],
    "created_at": "2026-03-05T12:00:00+00:00"
  },
  "message": "Webhook added successfully."
}

4. Guarda el valor de secret de la respuesta inmediatamente. El secreto solo se devuelve una vez y lo necesitas para verificar las firmas del webhook.

Puedes suscribir un webhook a cualquier combinación de eventos del ciclo de vida del despliegue:

• building: La compilación del despliegue ha comenzado.
• queued: El despliegue está en cola y esperando para ejecutarse.
• started: El despliegue ha comenzado a ejecutarse.
• completed: El despliegue se completó correctamente.
• failed: El despliegue falló.
• cancelled: El despliegue fue cancelado.

Si omites el parámetro events al crear un webhook, se suscribe a todos los eventos.

Cada entrega de webhook envía una solicitud HTTP POST con un cuerpo JSON que contiene detalles sobre el evento de despliegue.

Cada entrega incluye los siguientes encabezados HTTP:

• Content-Type: Siempre application/json.
• User-Agent: Identifica el origen: WPCOM-Code-Deployments-Webhook/1.0.
• X-WPCOM-Event: El evento que activó la entrega.
• X-WPCOM-Delivery-Attempt: El número de intento de entrega (1–3).
• X-WPCOM-Signature: Firma HMAC-SHA256 para verificar la autenticidad.

El cuerpo JSON contiene los siguientes campos:

{
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "completed",
  "deployment_run": {
    "id": 123,
    "status": "completed",
    "created_at": "2026-03-05T12:00:00+00:00",
    "started_at": "2026-03-05T12:00:05+00:00",
    "completed_at": "2026-03-05T12:01:30+00:00",
    "duration_seconds": 85,
    "failure_code": null
  },
  "deployment": {
    "id": 456,
    "target_dir": "/wp-content",
    "is_automated": true,
    "workflow_path": ".github/workflows/deploy.yml"
  },
  "site": {
    "id": 12345678,
    "name": "My Site",
    "url": "https://yourgroovydomain.com"
  },
  "repository": {
    "id": 987654,
    "name": "owner/repo",
    "branch": "main",
    "url": "https://github.com/owner/repo"
  },
  "commit": {
    "sha": "abc123def456789...",
    "short_sha": "abc123d",
    "message": "Update theme styles",
    "author": {
      "name": "Jane Doe",
      "github_id": 12345,
      "avatar_url": "https://avatars.githubusercontent.com/u/12345",
      "profile_url": "https://github.com/janedoe"
    }
  },
  "triggered_by": {
    "user_id": 67890,
    "display_name": "Jane Doe"
  },
  "links": {
    "logs": "https://wordpress.com/github-deployments/yourgroovydomain.com/logs/456",
    "github_workflow": "https://github.com/owner/repo/actions/runs/789"
  }
}

Algunos campos del payload devuelven null dependiendo del estado del despliegue:

• triggered_by es null para despliegues automatizados.
• deployment_run.duration_seconds es null hasta que el despliegue se completa.
• deployment_run.failure_code es null a menos que el despliegue haya fallado.
• links.github_workflow es null si no hay un flujo de trabajo de GitHub Actions configurado.

Cada entrega de webhook se firma con el secreto devuelto cuando creaste el webhook. La firma aparece en el encabezado X-WPCOM-Signature con el formato sha256=<hex-digest>.

Para verificar una entrega de webhook:

1. Calcula el hash HMAC-SHA256 del cuerpo de la solicitud sin procesar utilizando tu secreto de webhook como clave.
2. Compara el hash calculado con el valor del encabezado X-WPCOM-Signature después de eliminar el prefijo sha256=.
3. Rechaza la solicitud si los valores no coinciden.

Los siguientes ejemplos demuestran la verificación de firma en diferentes lenguajes.

Línea de comandos:

echo -n '<raw JSON body>' | openssl dgst -sha256 -hmac '<your webhook secret>'

PHP:

$payload   = file_get_contents( 'php://input' );
$secret    = 'your_webhook_secret';
$signature = 'sha256=' . hash_hmac( 'sha256', $payload, $secret );
if ( ! hash_equals( $signature, $_SERVER['HTTP_X_WPCOM_SIGNATURE'] ) ) {
    http_response_code( 403 );
    exit( 'Invalid signature' );
}

Node.js:

const crypto = require( 'crypto' );
function verifySignature( payload, secret, signatureHeader ) {
  const expected = 'sha256=' + crypto.createHmac( 'sha256', secret )
    .update( payload ).digest( 'hex' );
  return crypto.timingSafeEqual(
    Buffer.from( expected ),
    Buffer.from( signatureHeader )
  );
}

Puedes listar, actualizar, eliminar y probar webhooks a través de la API REST de WordPress.com. Todos los endpoints comparten la misma ruta base:

/wpcom/v2/sites/{site_id}/hosting/code-deployments/{deployment_id}/webhooks

Para recuperar todos los webhooks de una conexión de despliegue, envía una solicitud GET a la ruta base:

GET /wpcom/v2/sites/{site_id}/hosting/code-deployments/{deployment_id}/webhooks

La respuesta incluye la URL de cada webhook, los eventos suscritos y las estadísticas de entrega. El secreto del webhook no se incluye en las respuestas de listado.

Para cambiar la URL o los eventos suscritos de un webhook, envía una solicitud PUT:

PUT .../webhooks/{webhook_id}

El endpoint acepta los siguientes parámetros:

• url (obligatorio): La nueva URL del webhook.
• events (opcional): Nueva lista de eventos separados por comas.

No puedes cambiar el secreto de un webhook. Para rotar un secreto, elimina el webhook y crea uno nuevo.

Para eliminar un webhook, envía una solicitud DELETE:

DELETE .../webhooks/{webhook_id}

Para enviar una entrega de prueba a un webhook, envía una solicitud POST:

POST .../webhooks/{webhook_id}/test

La entrega de prueba se ejecuta inmediatamente y devuelve el resultado en la respuesta. Utiliza un único intento de entrega con datos de despliegue de ejemplo, firmados con el secreto del webhook.

Ejemplo de respuesta:

{
  "success": true,
  "delivery_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status_code": 200,
  "duration_ms": 145,
  "error": null
}

Para ver las entregas recientes de un webhook, envía una solicitud GET:

GET .../webhooks/{webhook_id}/deliveries

La respuesta devuelve las últimas 10 entregas, de la más reciente a la más antigua. Cada registro incluye el tipo de evento, el código de estado HTTP, el tiempo de respuesta, el número de intento y cualquier mensaje de error.

Las entregas de webhooks se ejecutan en segundo plano y no retrasan ni bloquean tus despliegues. Las siguientes reglas se aplican a los intentos de entrega:

• Si una entrega falla (respuesta no 2xx o error de red), el sistema reintenta hasta tres veces con intervalos de 1, 5 y 15 segundos entre intentos.
• Cada intento de entrega tiene un tiempo de espera de 10 segundos.
• Las últimas 10 entregas por webhook se almacenan y están disponibles a través del endpoint de historial de entregas.