Skip to content

feat: implement Caddy certificate event webhook plugin#1

Merged
pcfreak30 merged 3 commits into
developfrom
init
Feb 26, 2026
Merged

feat: implement Caddy certificate event webhook plugin#1
pcfreak30 merged 3 commits into
developfrom
init

Conversation

@pcfreak30

@pcfreak30 pcfreak30 commented Feb 26, 2026

Copy link
Copy Markdown
Member

Add initial implementation of Caddy plugin that hooks into certificate
lifecycle events and sends webhooks to a central portal service.

Core features:

  • Subscribe to Caddy certificate events (cert_obtained, cert_renewed, cert_expired)
  • Event-driven webhook delivery with authentication
  • Async webhook delivery with exponential backoff retry
  • Status mapping from Caddy events to portal SSL statuses
  • Configuration via Caddyfile and JSON
  • Environment variable support for secrets

Implementation:

  • WebhookClient handles HTTP communication with portal
  • WebhookDelivery manages async delivery with retry logic
  • RetryWithBackoff implements exponential backoff for transient errors
  • Event handlers extract domain, timestamp, and error data
  • Comprehensive test coverage (unit, integration, retry logic)

Build:

  • GitHub Actions workflow for CI testing
  • Go module setup with Caddy v2.11.1 dependency

This pull request introduces the initial implementation of a Caddy v2 plugin that provides real-time SSL certificate status updates to a central portal service via webhooks.

Key Features:

  • Certificate Event Monitoring: Subscribes to Caddy's TLS certificate lifecycle events (cert_obtained, cert_renewed, cert_expired) to track when certificates are issued, renewed, or expire.
  • Portal Integration: Sends authenticated webhook notifications to a configurable portal endpoint (/internal/websites/:domain/ssl-status) using X-Gateway-Secret header authentication.
  • Status Mapping: Translates Caddy certificate events into portal-specific SSL statuses (ready, failed, pending, issuing), including error details when certificate operations fail.
  • Reliable Delivery: Implements asynchronous, non-blocking webhook delivery to prevent disruption of certificate operations. Includes exponential backoff retry logic (default 5 attempts) for transient failures (5xx errors, network timeouts).
  • Flexible Configuration: Supports configuration via Caddyfile (cert_webhook directive) and environment variables (PORTAL_URL, GATEWAY_SECRET), with configurable HTTP timeouts and retry limits.
  • Operational Safety: Implements graceful shutdown handling to ensure pending webhook deliveries complete during Caddy configuration reloads.

Components Added:

  • Event subscription and handling logic for Caddy's event system
  • HTTP client for portal communication with retry mechanisms
  • Asynchronous delivery manager with graceful shutdown support
  • Configuration management with environment variable support
  • OpenAPI specification and generated client code for portal API integration
  • Comprehensive test suite covering client behavior, status mapping, and integration scenarios
  • CI/CD workflow and documentation

This implementation enables real-time tracking of SSL certificate health across gateway infrastructure through automated webhook notifications to the central portal.


This pull request introduces a new Caddy v2 plugin that enables real-time SSL certificate lifecycle event tracking by sending webhooks to a central portal service.

Key Features Implemented:

  • Certificate Event Subscription: Hooks into Caddy's TLS certificate events (cert_obtained, cert_renewed, cert_expired) to monitor certificate lifecycle changes
  • Portal Integration: Sends authenticated webhook notifications to a configurable portal endpoint (/internal/websites/:domain/ssl-status) with X-Gateway-Secret header authentication
  • SSL Status Mapping: Translates Caddy certificate events into standardized portal SSL statuses (pending, issuing, ready, failed)
  • Asynchronous Delivery: Implements non-blocking webhook delivery with exponential backoff retry logic (up to 5 attempts) to ensure certificate operations are never disrupted by webhook delivery failures
  • Configuration Support: Supports configuration via Caddyfile directives (portal_url, timeout, retry_count) and environment variables (PORTAL_URL, GATEWAY_SECRET)
  • Operational Safety: Includes graceful cleanup handling for Caddy configuration reloads and comprehensive error handling that distinguishes between transient (5xx) and permanent (4xx) failures

Testing & Tooling:

  • Comprehensive test suite covering unit tests, client tests, status mapping tests, and integration tests for async delivery scenarios
  • GitHub Actions workflow for automated testing on Go 1.26
  • OpenAPI/Swagger specification for the portal API integration
  • Generated client code for type-safe portal API communication

This plugin allows infrastructure teams to maintain real-time visibility into SSL certificate status across their Caddy deployments without impacting certificate issuance performance.

@pcfreak30

Copy link
Copy Markdown
Member Author

@kody review

@kody-ai

kody-ai Bot commented Feb 26, 2026

Copy link
Copy Markdown

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

  • Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug
Performance
Security
Cross File

Access your configuration settings here.

Comment thread delivery.go
Comment thread delivery.go
Comment thread portal.go
Comment thread portal.go
Comment thread portal.go Outdated
Comment thread portal.go
Add initial implementation of Caddy plugin that hooks into certificate
lifecycle events and sends webhooks to a central portal service.

Core features:
- Subscribe to Caddy certificate events (cert_obtained, cert_renewed, cert_expired)
- Event-driven webhook delivery with authentication
- Async webhook delivery with exponential backoff retry
- Status mapping from Caddy events to portal SSL statuses
- Configuration via Caddyfile and JSON
- Environment variable support for secrets

Implementation:
- WebhookClient handles HTTP communication with portal
- WebhookDelivery manages async delivery with retry logic
- RetryWithBackoff implements exponential backoff for transient errors
- Event handlers extract domain, timestamp, and error data
- Comprehensive test coverage (unit, integration, retry logic)

Build:
- GitHub Actions workflow for CI testing
- Go module setup with Caddy v2.11.1 dependency
@kody-ai

kody-ai Bot commented Feb 26, 2026

Copy link
Copy Markdown

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

  • Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug
Performance
Security
Cross File

Access your configuration settings here.

- Add semaphore to limit concurrent webhook delivery goroutines (prevents resource exhaustion)
- Add timestamp field to webhook delivery error logs for consistency
- Fix nil HTTP client panic by using http.DefaultClient fallback
- Always send X-Gateway-Secret header even if empty (prevents auth bypass)
- Add endpoint validation to prevent SSRF via untrusted configuration
- Use byte iteration in validEndpoint for ASCII-only validation
@pcfreak30 pcfreak30 merged commit f5ab584 into develop Feb 26, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant