feat(webhooks): emit lifecycle events to a configured endpoint (phase 1) (#257)

Generalizes outbound webhook delivery into a unified lifecycle-event bus (#256
phase 1). Handlers publish typed events; a dispatcher signs and delivers them
asynchronously, off the request path, with bounded retry and an SSRF guard —
the same posture as the existing cert-expiry alerter, now shared.

- internal/webhook: Event envelope {id,type,created_at,data} + Dispatcher
  (async queue, linear-backoff retry, HMAC-SHA256 signing, X-Nebula-Event/
  Delivery/Signature headers, request-time SSRF guard, event-type allowlist,
  graceful Close). Emit is non-blocking and nil-safe.
- config: a webhooks block (enabled/url/hmac_secret/allow_private/events) with
  the URL SSRF-validated at load; validateWebhookURL generalized to name the
  offending key so alerts and webhooks share it.
- api.Server: a narrow EventEmitter seam (no webhook import) + nil-safe emit.
  Handlers emit host.enrolled (enroll), host.blocked/unblocked (block/unblock),
  host.deleted (delete), and cert.rotated (in-place re-sign).
- serve.go: build the dispatcher when enabled, inject it into the API server,
  drain it on shutdown, and fold cert.expiring into the bus via an adapter sink
  on the cert-expiry scanner.
- api/openapi.yaml: a 3.1 webhooks block documenting the six events; a contract
  test drives the real handlers and validates every emitted payload against the
  schemas (drift breaks the build).
- docs/webhooks.md: configuration, signature verification, delivery semantics.

Phase 2 (managed subscriptions, ca.expiring, durable dead-letter queue) stays
tracked in #256.

Refs #256

Author: juev

api/openapi.yaml

@@ -198,6 +198,90 @@ paths:
                 items:
                   $ref: "#/components/schemas/AuditEntry"
 
+# Outbound webhooks the server POSTs to an operator-configured endpoint (#256).
+# Each delivery carries X-Nebula-Event (type), X-Nebula-Delivery (id), and
+# X-Nebula-Signature (sha256=<hmac> over the raw body). The handler/scanner emit
+# shapes are validated against these schemas by the contract tests.
+webhooks:
+  host.enrolled:
+    post:
+      operationId: webhookHostEnrolled
+      summary: A host completed enrollment and received its first certificate.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/HostEnrolledEvent"
+      responses:
+        "2XX":
+          description: Acknowledged.
+  host.blocked:
+    post:
+      operationId: webhookHostBlocked
+      summary: A host was blocked and its certificate revoked.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/HostEvent"
+      responses:
+        "2XX":
+          description: Acknowledged.
+  host.unblocked:
+    post:
+      operationId: webhookHostUnblocked
+      summary: A previously blocked host was unblocked.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/HostEvent"
+      responses:
+        "2XX":
+          description: Acknowledged.
+  host.deleted:
+    post:
+      operationId: webhookHostDeleted
+      summary: A host was deleted and its certificate revoked.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/HostEvent"
+      responses:
+        "2XX":
+          description: Acknowledged.
+  cert.rotated:
+    post:
+      operationId: webhookCertRotated
+      summary: A host certificate was re-signed (in-place rotation).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CertRotatedEvent"
+      responses:
+        "2XX":
+          description: Acknowledged.
+  cert.expiring:
+    post:
+      operationId: webhookCertExpiring
+      summary: A host certificate is approaching expiry without renewal.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CertExpiringEvent"
+      responses:
+        "2XX":
+          description: Acknowledged.
+
 components:
   securitySchemes:
     bearerAuth:
@@ -414,3 +498,109 @@ components:
           type: string
         details:
           type: string
+
+    # --- Webhook event envelopes (#256) ---
+
+    HostEventData:
+      type: object
+      required: [host_id, host_name, network_id, ca_id]
+      properties:
+        host_id:
+          type: string
+        host_name:
+          type: string
+        network_id:
+          type: string
+        ca_id:
+          type: string
+
+    HostEnrolledData:
+      type: object
+      required: [host_id, host_name, network_id, ca_id, fingerprint]
+      properties:
+        host_id:
+          type: string
+        host_name:
+          type: string
+        network_id:
+          type: string
+        ca_id:
+          type: string
+        fingerprint:
+          type: string
+
+    CertExpiringData:
+      type: object
+      required: [host_id, host_name, network_id, ca_id, fingerprint, not_after, seconds_until_expiry]
+      properties:
+        host_id:
+          type: string
+        host_name:
+          type: string
+        network_id:
+          type: string
+        ca_id:
+          type: string
+        fingerprint:
+          type: string
+        not_after:
+          type: string
+          format: date-time
+        seconds_until_expiry:
+          type: number
+
+    HostEvent:
+      type: object
+      required: [id, type, created_at, data]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        data:
+          $ref: "#/components/schemas/HostEventData"
+
+    HostEnrolledEvent:
+      type: object
+      required: [id, type, created_at, data]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        data:
+          $ref: "#/components/schemas/HostEnrolledData"
+
+    CertRotatedEvent:
+      type: object
+      required: [id, type, created_at, data]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        data:
+          $ref: "#/components/schemas/HostEnrolledData"
+
+    CertExpiringEvent:
+      type: object
+      required: [id, type, created_at, data]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        data:
+          $ref: "#/components/schemas/CertExpiringData"

docs/webhooks.md

@@ -0,0 +1,84 @@
+# Webhooks
+
+The server can POST lifecycle events to an operator-configured HTTP endpoint so
+external systems react to mesh changes without polling — inventory/CMDB sync on
+enrollment, SOC alerting on block/revoke, automation on cert rotation. Delivery
+is asynchronous (off the request path), signed, and SSRF-guarded.
+
+The machine-readable contract for every event lives in
+[`api/openapi.yaml`](../api/openapi.yaml) under `webhooks:`; the contract tests
+validate the real emitted payloads against it.
+
+## Enabling
+
+```yaml
+# server.yml
+webhooks:
+  enabled: true
+  url: https://hooks.example.com/nebula
+  hmac_secret: "<random secret>"        # optional; signs each delivery
+  events: [host.enrolled, host.blocked] # optional; empty = all events
+  allow_private: false                  # set true only for an intentional internal sink
+```
+
+`url` is validated at startup (must be http/https; loopback/private/link-local
+targets are rejected unless `allow_private: true`).
+
+## Events (phase 1)
+
+| Event | Fires when | `data` fields |
+|---|---|---|
+| `host.enrolled` | a host completes enrollment | `host_id`, `host_name`, `network_id`, `ca_id`, `fingerprint` |
+| `host.blocked` | a host is blocked (cert revoked) | `host_id`, `host_name`, `network_id`, `ca_id` |
+| `host.unblocked` | a blocked host is unblocked | same as `host.blocked` |
+| `host.deleted` | a host is deleted (cert revoked) | same as `host.blocked` |
+| `cert.rotated` | a host cert is re-signed in place | host fields + new `fingerprint` |
+| `cert.expiring` | a cert approaches expiry without renewal | host fields + `fingerprint`, `not_after`, `seconds_until_expiry` |
+
+`cert.expiring` is produced by the cert-expiry scanner, so it requires
+`alerts.enabled: true` (the scanner) in addition to `webhooks.enabled`. The
+other events come from the API handlers and need only the webhooks block.
+
+## Delivery format
+
+Every delivery is `POST <url>` with `Content-Type: application/json` and a body:
+
+```json
+{
+  "id": "evt_2f1c…",
+  "type": "host.blocked",
+  "created_at": "2026-06-13T12:00:00Z",
+  "data": { "host_id": "…", "host_name": "…", "network_id": "…", "ca_id": "…" }
+}
+```
+
+Headers:
+
+- `X-Nebula-Event` — the event type (also in the body).
+- `X-Nebula-Delivery` — the unique event id; use it to deduplicate (delivery is at-least-once).
+- `X-Nebula-Signature` — `sha256=<hex>`, the HMAC-SHA256 of the raw body under `hmac_secret` (present only when a secret is set).
+
+## Verifying the signature
+
+Compute `HMAC-SHA256(hmac_secret, raw_request_body)` and compare, in constant
+time, against the hex in `X-Nebula-Signature` (after the `sha256=` prefix).
+Reject deliveries that do not match.
+
+## Reliability
+
+- **Asynchronous**: events are queued and delivered by a background worker; a
+  slow or down receiver never blocks an API request.
+- **Retried**: a failed delivery (connection error or HTTP ≥ 400) is retried a
+  few times with linear backoff. After the retries are exhausted the event is
+  logged and dropped (a durable dead-letter queue is a later phase).
+- **Best-effort under load**: if the in-memory queue is full the event is
+  dropped with a logged warning rather than stalling the server. Treat webhooks
+  as a notification stream, not a system of record — the audit log remains the
+  authoritative history.
+
+## Not in phase 1
+
+- Managed subscriptions (multiple endpoints, CRUD, per-subscription status) —
+  phase 1 is a single config-driven subscription.
+- `ca.expiring` and other CA-lifecycle events.
+- A persistent dead-letter queue and delivery dashboards.

internal/api/enroll.go

@@ -236,6 +236,13 @@ func (s *Server) handleEnroll(w http.ResponseWriter, r *http.Request) {
 	}
 
 	s.metrics.recordEnrollment(resultOK)
+	s.emit("host.enrolled", map[string]any{
+		"host_id":     host.ID,
+		"host_name":   host.Name,
+		"network_id":  host.NetworkID,
+		"ca_id":       host.CAID,
+		"fingerprint": fp,
+	})
 	writeJSON(w, http.StatusOK, enrollResponse{
 		CertificatePEM:   string(certPEM),
 		CACertificatePEM: string(caCertPEM),