keenauth_webhook_endpoint

Die Ressource keenauth_webhook_endpoint verwaltet einen Webhook-Endpunkt: eine HTTPS-Adresse, die die Ereignisse der Umgebung empfängt und mit Standard Webhooks signiert wird. Der Provider speichert das Signaturgeheimnis nur verschlüsselt mit einem RSA-Public-Key, den Sie ihm übergeben, im State.

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
}

Argumente

• url ist erforderlich: nur https, kein Port oder Port 443, keine Benutzerinformationen, kein Fragment und ein Hostname statt einer IP-Adresse (höchstens 2048 Zeichen).
• key ist in der Umgebung eindeutig (^[a-z0-9][a-z0-9_-]{0,63}$). Wenn Sie ihn weglassen, leitet die API endpoint-<letzte 8 Zeichen der ID> ab.
• event_types listet Ereignistypen aus dem Katalog auf (höchstens 100). Eine leere Menge, der Standardwert, bedeutet alle Typen außer den umfangreichen authentication.*-Typen, die Sie ausdrücklich nennen müssen.
• event_schema_versions ordnet einem Ereignistyp eine Version des Payload-Schemas zu. Jeder Typ muss einer sein, den der Endpunkt empfängt.
• payload_mode ist thin (der Standardwert: IDs, geänderte Feldnamen und Statusfelder, keine personenbezogenen Daten) oder full.
• rate_limit_per_second liegt zwischen 1 und 1000; der Standardwert ist 50.
• status ist enabled (der Standardwert) oder disabled_by_user.

Jedes Argument wird direkt aktualisiert. Updates senden nur die geänderten Felder als JSON Merge Patch, mit dem ETag des letzten Lesevorgangs als If-Match. Wurde der Endpunkt seit dem letzten Lesen anderswo geändert, schlägt das Apply mit 412 fehl, und nichts wird geändert; führen Sie plan erneut aus, um die Abweichung zu prüfen.

Das Signaturgeheimnis wird nie im Klartext gespeichert

Die API gibt das Signaturgeheimnis (idp_whsec_…) nur beim Erstellen des Endpunkts und bei einer Rotation des Geheimnisses zurück. Mit public_key verschlüsselt der Provider das Geheimnis mit RSA-OAEP (SHA-256, MGF1 SHA-256, leeres Label) und schreibt nur den Base64-Chiffretext nach encrypted_signing_secret. Ohne public_key wird das Geheimnis verworfen; rotieren Sie es später mit keenauth webhook-endpoints rotate-secret oder setzen Sie public_key. Das Klartext-Geheimnis gelangt weder in den State, eine Plan-Datei, eine Ausgabe noch in ein Log.

Erzeugen Sie das Schlüsselpaar einmalig außerhalb von OpenTofu und halten Sie den privaten Schlüssel aus Ihrer Konfiguration heraus:

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

Nach tofu apply entschlüsseln Sie das Geheimnis und geben es an den Empfänger weiter:

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 muss ein PEM-kodierter RSA-Public-Key (PUBLIC KEY oder RSA PUBLIC KEY) mit mindestens 2048 Bit sein. Ein privater Schlüssel oder ein kleinerer Schlüssel wird bereits bei plan abgelehnt.

Rotation

Das Geheimnis wird rotiert, wenn Sie public_key setzen oder ändern und wenn sich rotation_trigger auf einen neuen Wert ändert, zum Beispiel auf die ID einer time_rotating-Ressource. Nach einer Rotation signiert das alte Geheimnis zusammen mit dem neuen weiter, und zwar für previous_secret_ttl_hours (0 bis 168; der API-Standardwert ist 24; 0 verwirft es sofort), damit der Empfänger ohne verpasste Ereignisse umstellen kann. previous_secret_expires_at zeigt, wann das alte Geheimnis endet. Das Entfernen von public_key entfernt nur encrypted_signing_secret; es rotiert das Geheimnis nicht.

Limits und Status

Ein aktivierter Endpunkt zählt pro Umgebung auf das Limit des Plans: Free 3, Startup 20, Business 20, Enterprise 50. Das Erstellen oder Aktivieren eines weiteren schlägt mit 403 quota_exceeded fehl; deaktivieren oder löschen Sie einen anderen Endpunkt oder wechseln Sie den Plan.

KeenAuth deaktiviert einen Endpunkt, der immer wieder fehlschlägt (disabled_by_failure), oder dessen Empfänger mit 410 Gone antwortet (disabled_by_receiver). Der nächste plan zeigt die Änderung zurück auf den konfigurierten status, und das Anwenden aktiviert den Endpunkt wieder.

Import

Importieren Sie mit der Endpunkt-ID oder seinem Schlüssel:

tofu import keenauth_webhook_endpoint.orders orders

Das Signaturgeheimnis kann nicht zurückgelesen werden, daher ist encrypted_signing_secret nach dem Import leer. Setzt Ihre Konfiguration public_key, rotiert das nächste Apply das Geheimnis und liefert das neue verschlüsselt aus.

Testsendungen, Wiederholungen und Zustellversuche sind einmalige Aktionen und keine Konfiguration. Verwenden Sie dafür keenauth webhook-endpoints test, replay und deliveries.