keenauth_webhook_endpoint

El recurso keenauth_webhook_endpoint gestiona un endpoint de webhook: una dirección HTTPS que recibe los eventos del entorno, firmados con Standard Webhooks. El proveedor mantiene el secreto de firma en el estado solo cifrado con una clave pública RSA que usted le proporciona.

resource "keenauth_webhook_endpoint" "orders" {
  key         = "orders"
  url         = "https://hooks.example.com/keenauth"
  description = "Order service"
  event_types = ["user.created", "user.updated", "organization.created"]
  event_schema_versions = {
    "user.created" = 1
  }
  public_key = file("${path.module}/webhook-secret-key.pub.pem")

  rotation_trigger          = time_rotating.webhook_secret.id
  previous_secret_ttl_hours = 48
}

resource "time_rotating" "webhook_secret" {
  rotation_days = 90
}

output "orders_webhook_secret_encrypted" {
  value = keenauth_webhook_endpoint.orders.encrypted_signing_secret
}

Argumentos

• url es obligatorio: solo https, sin puerto o con el puerto 443, sin información de usuario, sin fragmento, y con un nombre de host en lugar de una dirección IP (como máximo 2048 caracteres).
• key es único en el entorno (^[a-z0-9][a-z0-9_-]{0,63}$). Si lo omite, la API genera endpoint-<últimos 8 caracteres del ID>.
• event_types enumera los tipos de evento del catálogo (como máximo 100). Un conjunto vacío, que es el predeterminado, significa todos los tipos excepto los tipos authentication.* de alto volumen, que debe nombrar explícitamente.
• event_schema_versions asigna a un tipo de evento una versión del esquema de la carga útil. Cada tipo debe ser uno que el endpoint reciba.
• payload_mode es thin (el predeterminado: IDs, nombres de campos modificados y campos de estado, sin datos personales) o full.
• rate_limit_per_second va de 1 a 1000; el predeterminado es 50.
• status es enabled (el predeterminado) o disabled_by_user.

Cada argumento se cambia en su lugar. Las actualizaciones envían solo los campos modificados como JSON Merge Patch, con el ETag de la última lectura como If-Match. Si el endpoint se modificó en otro lugar después de la última lectura, el apply falla con 412 y no se cambia nada; ejecute plan de nuevo para revisar la desviación.

El secreto de firma nunca se almacena en texto plano

La API devuelve el secreto de firma (idp_whsec_…) solo cuando se crea el endpoint y cuando se rota el secreto. Con public_key, el proveedor cifra el secreto con RSA-OAEP (SHA-256, MGF1 SHA-256, etiqueta vacía) y escribe solo el texto cifrado en base64 en encrypted_signing_secret. Sin public_key, el secreto se descarta; rótelo más adelante con keenauth webhook-endpoints rotate-secret o establezca public_key. El secreto en texto plano nunca llega al estado, a un archivo de plan, a una salida ni a un registro.

Cree el par de claves una sola vez, fuera de OpenTofu, y mantenga la clave privada fuera de su configuración:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out webhook-secret-key.pem
openssl pkey -in webhook-secret-key.pem -pubout -out webhook-secret-key.pub.pem

Después de tofu apply, descifre el secreto y entréguelo al receptor:

tofu output -raw orders_webhook_secret_encrypted | base64 -d | \
  openssl pkeyutl -decrypt -inkey webhook-secret-key.pem \
    -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256

public_key debe ser una clave pública RSA codificada en PEM (PUBLIC KEY o RSA PUBLIC KEY) de al menos 2048 bits. Una clave privada o una clave más pequeña se rechaza en el momento del plan.

Rotación

El secreto se rota cuando establece o cambia public_key, y cuando rotation_trigger cambia a un valor nuevo, por ejemplo el ID de un recurso time_rotating. Después de una rotación, el secreto anterior sigue firmando junto al nuevo durante previous_secret_ttl_hours (de 0 a 168; el predeterminado de la API es 24; 0 lo elimina de inmediato), para que el receptor pueda cambiar sin perder eventos. previous_secret_expires_at muestra cuándo deja de funcionar el secreto anterior. Eliminar public_key solo elimina encrypted_signing_secret; no rota el secreto.

Límites y estado

Un endpoint habilitado cuenta para el límite del plan por entorno: Free 3, Startup 20, Business 20, Enterprise 50. Crear o habilitar uno más falla con 403 quota_exceeded; deshabilite o elimine otro endpoint, o actualice el plan.

KeenAuth deshabilita un endpoint que sigue fallando (disabled_by_failure) o cuyo receptor responde 410 Gone (disabled_by_receiver). El siguiente plan muestra el cambio de vuelta al status configurado, y al aplicarlo el endpoint vuelve a habilitarse.

Importación

Importe con el ID del endpoint o con su clave:

tofu import keenauth_webhook_endpoint.orders orders

El secreto de firma no se puede leer de nuevo, así que encrypted_signing_secret queda vacío después de la importación. Si su configuración establece public_key, el siguiente apply rota el secreto y entrega el nuevo cifrado.

Los envíos de prueba, las repeticiones y los reintentos de entrega son acciones puntuales, no configuración. Para ellos use keenauth webhook-endpoints test, replay y deliveries.