[PR #158] Customizable Webhook Body Templating #168

New issue

Open

opened 2026-02-26 21:34:50 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 21:34:50 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/eduardolat/pgbackweb/pull/158
Author: @Ragug
Created: 12/1/2025
Status: 🔄 Open

Base: develop ← Head: feature/webhook-body-templating

📝 Commits (1)

c489c90 feat: Allow customizable webhook body using Go templates

📊 Changes

10 files changed (+500 additions, -38 deletions)

View changed files

📝 internal/service/databases/test_database.go (+54 -2)
📝 internal/service/destinations/test_destination.go (+45 -2)
📝 internal/service/executions/run_execution.go (+51 -11)
📝 internal/service/executions/run_execution.sql (+4 -0)
➕ internal/service/webhooks/payload.go (+69 -0)
📝 internal/service/webhooks/run_webhook.go (+31 -13)
📝 internal/service/webhooks/send_webhook_request.go (+9 -2)
➕ internal/service/webhooks/utils.go (+129 -0)
📝 internal/view/web/dashboard/webhooks/common.go (+104 -7)
📝 internal/view/web/dashboard/webhooks/run_webhook.go (+4 -1)

📄 Description

🚀 Pull Request: Customizable Webhook Body Templating

This PR introduces the ability to use Go's text/template syntax to define the JSON body of outgoing webhooks, replacing the previous static body or simple JSON object.

This feature is inspired by the highly flexible and customizable webhook payloads found in professional monitoring and visualization tools like Uptime Kuma and Grafana, ensuring pgbackweb can integrate seamlessly with virtually any external notification system.

This change required a comprehensive refactoring of the webhook data flow to ensure all necessary event context is correctly built and passed down to the rendering layer.

✨ Key Changes & Features

1. Customizable Webhook Body

The Body field for a webhook now accepts a Go text/template string.
This allows users to create rich, custom payloads in JSON, dynamically injecting data fields like database name, execution status, and file size.
Helper Functions (formatTime, formatFileSize) are exposed in the template context for easy data formatting.

2. Standardized Event Payloads

To support templating, the webhook data flow was standardized using three new structs:

internal/service/webhooks/payload.go: Defines the new payload structures:
- DatabaseStatus
- DestinationStatus
- ExecutionDetails
- WebhookPayload: The main struct passed to the template, containing the above three structs plus EventType and Msg.

3. Refactored Service Runners

All event triggers (RunDatabaseHealthy, RunDestinationUnhealthy, RunExecutionSuccess, etc.) are updated across the application to pre-build and pass the detailed DatabaseStatus, DestinationStatus, or full WebhookPayload.
This ensures the exact state at the time of the event is captured and used for the webhook.

4. Improved UI Documentation

The Webhooks Edit/Create form now includes a detailed template helper panel to guide users.
The panel lists all available template fields (.Database.Name, .Execution.FileSize, etc.), provides syntax examples, and documents the available helper functions.

💻 Code Changes & Technical Notes

File/Package	Change Description
`internal/service/webhooks/payload.go` (NEW)	Defines the new data models for structured payloads.
`internal/service/webhooks/utils.go` (NEW)	Contains utility functions: `ParsePostgresURL`, `RenderWebhookBody`, and `buildMessage`. Registers template functions like `formatFileSize`.
`internal/service/{databases, destinations, executions}`	Updated runners to build and pass the structured status data instead of just the ID.
`internal/service/webhooks/run_webhook.go`	Updated all runner methods and `runWebhook` to accept and use the `WebhookPayload`.
`internal/service/webhooks/send_webhook_request.go`	Now calls `RenderWebhookBody` to transform the template string into the final HTTP body.
`internal/view/web/dashboard/webhooks/common.go`	Significantly updated to add template documentation and a better default placeholder.

💬 Maintainer Feedback and Review Notes ⚙️

This feature represents a massive and necessary improvement to the maintainability and flexibility of the webhook system.

The core motivation for this refactor—to eliminate the burden of configuring and maintaining separate, hard-coded JSON payloads for every database and status change—has been successfully addressed by introducing centralized templating. This vastly reduces overhead for administrators.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/eduardolat/pgbackweb/pull/158 **Author:** [@Ragug](https://github.com/Ragug) **Created:** 12/1/2025 **Status:** 🔄 Open **Base:** `develop` ← **Head:** `feature/webhook-body-templating` --- ### 📝 Commits (1) - [`c489c90`](https://github.com/eduardolat/pgbackweb/commit/c489c900e7d8c88fb6929a47d9ede0518a3a632c) feat: Allow customizable webhook body using Go templates ### 📊 Changes **10 files changed** (+500 additions, -38 deletions) <details> <summary>View changed files</summary> 📝 `internal/service/databases/test_database.go` (+54 -2) 📝 `internal/service/destinations/test_destination.go` (+45 -2) 📝 `internal/service/executions/run_execution.go` (+51 -11) 📝 `internal/service/executions/run_execution.sql` (+4 -0) ➕ `internal/service/webhooks/payload.go` (+69 -0) 📝 `internal/service/webhooks/run_webhook.go` (+31 -13) 📝 `internal/service/webhooks/send_webhook_request.go` (+9 -2) ➕ `internal/service/webhooks/utils.go` (+129 -0) 📝 `internal/view/web/dashboard/webhooks/common.go` (+104 -7) 📝 `internal/view/web/dashboard/webhooks/run_webhook.go` (+4 -1) </details> ### 📄 Description ## 🚀 Pull Request: Customizable Webhook Body Templating This PR introduces the ability to use Go's `text/template` syntax to define the JSON body of outgoing webhooks, replacing the previous static body or simple JSON object. This feature is inspired by the highly flexible and customizable webhook payloads found in professional monitoring and visualization tools like **Uptime Kuma** and **Grafana**, ensuring `pgbackweb` can integrate seamlessly with virtually any external notification system. This change required a comprehensive refactoring of the webhook data flow to ensure all necessary event context is correctly built and passed down to the rendering layer. --- ## ✨ Key Changes & Features ### 1. **Customizable Webhook Body** * The `Body` field for a webhook now accepts a **Go `text/template` string**. * This allows users to create rich, custom payloads in JSON, dynamically injecting data fields like database name, execution status, and file size. * **Helper Functions** (`formatTime`, `formatFileSize`) are exposed in the template context for easy data formatting. ### 2. **Standardized Event Payloads** To support templating, the webhook data flow was standardized using three new structs: * `internal/service/webhooks/payload.go`: Defines the new payload structures: * `DatabaseStatus` * `DestinationStatus` * `ExecutionDetails` * `WebhookPayload`: The main struct passed to the template, containing the above three structs plus `EventType` and `Msg`. ### 3. **Refactored Service Runners** * All event triggers (`RunDatabaseHealthy`, `RunDestinationUnhealthy`, `RunExecutionSuccess`, etc.) are updated across the application to **pre-build** and pass the detailed `DatabaseStatus`, `DestinationStatus`, or full `WebhookPayload`. * This ensures the exact state at the time of the event is captured and used for the webhook. ### 4. **Improved UI Documentation** * The Webhooks Edit/Create form now includes a detailed **template helper panel** to guide users. * The panel lists all available template fields (`.Database.Name`, `.Execution.FileSize`, etc.), provides syntax examples, and documents the available helper functions. --- ## 💻 Code Changes & Technical Notes | File/Package | Change Description | | :--- | :--- | | `internal/service/webhooks/payload.go` (NEW) | Defines the new **data models** for structured payloads. | | `internal/service/webhooks/utils.go` (NEW) | Contains utility functions: `ParsePostgresURL`, `RenderWebhookBody`, and `buildMessage`. Registers template functions like **`formatFileSize`**. | | `internal/service/{databases, destinations, executions}` | Updated runners to **build and pass** the structured status data instead of just the ID. | | `internal/service/webhooks/run_webhook.go` | Updated all runner methods and `runWebhook` to accept and use the `WebhookPayload`. | | `internal/service/webhooks/send_webhook_request.go` | Now calls `RenderWebhookBody` to transform the template string into the final HTTP body. | | `internal/view/web/dashboard/webhooks/common.go` | Significantly updated to add template documentation and a better default placeholder. | --- ## 💬 Maintainer Feedback and Review Notes ⚙️ This feature represents a **massive and necessary improvement** to the maintainability and flexibility of the webhook system. The core motivation for this refactor—**to eliminate the burden of configuring and maintaining separate, hard-coded JSON payloads for every database and status change**—has been successfully addressed by introducing centralized templating. This vastly reduces overhead for administrators. <img width="590" height="980" alt="image" src="https://github.com/user-attachments/assets/d86f1451-c329-4356-8ce5-f3656779f5d9" /> <img width="1147" height="792" alt="image" src="https://github.com/user-attachments/assets/afd9d2cc-3338-40be-9ad6-8fef178c6424" /> <img width="866" height="800" alt="image" src="https://github.com/user-attachments/assets/d01c31ab-734b-4114-9552-f439e76079f8" /> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>