Webhooks

License Required

Webhooks require the Webhooks license add-on. Without this license, webhook functionality will not be available.

Webhooks allow BadgerPanel to send real-time HTTP notifications to external services when specific events occur. Use webhooks to integrate with Discord, Slack, monitoring tools, or custom applications.

---

Supported Webhook Types

BadgerPanel supports three webhook types:

Type	Description
Discord	Sends formatted embed messages to a Discord channel via a Discord webhook URL. Messages include event details, colors, and timestamps in Discord's expected format.
Slack	Sends structured messages to a Slack channel via a Slack Incoming Webhook URL. Messages use Slack's Block Kit format.
Custom HTTP	Sends a JSON payload to any HTTP endpoint. The payload includes the event type, timestamp, and event-specific data. Use this for custom integrations or third-party services.

---

Creating a Webhook

1. Navigate to Admin > Webhooks and click Create Webhook.
2. Fill in the webhook details:
   • Name - a descriptive name (e.g., "Discord Alerts", "Billing Notifications")
   • Type - select Discord, Slack, or Custom
   • URL - the destination URL:
     • For Discord: the full webhook URL from your channel's integration settings
     • For Slack: the Incoming Webhook URL from your Slack app configuration
     • For Custom: any HTTPS endpoint that accepts POST requests
   • Secret - an optional shared secret for custom webhooks. When set, BadgerPanel includes an HMAC-SHA256 signature in the X-Webhook-Signature header so your endpoint can verify authenticity.
   • Enabled - toggle the webhook on or off
3. Select the Events to subscribe to (see below).
4. Click Save.

---

Event Types

Each webhook can subscribe to a specific set of events, organized by category:

Category	Events
Servers	server.created, server.deleted, server.suspended, server.unsuspended, server.started, server.stopped, server.install_completed, server.install_failed
Users	user.created, user.deleted, user.suspended
Nodes	node.online, node.offline, node.error, node.maintenance
Billing	order.created, order.paid, invoice.paid, invoice.overdue, service.suspended, service.terminated
Support	ticket.created, ticket.replied, ticket.closed

Select only the events relevant to each webhook to avoid unnecessary traffic. You can update the subscribed events at any time from the webhook detail page.

---

Webhook Delivery

When a subscribed event occurs, BadgerPanel sends an HTTP POST request to the webhook URL. The request includes the following headers:

Header	Description
Content-Type	application/json
User-Agent	BadgerPanel-Webhook/1.0
X-Webhook-Event	The event type (e.g., server.created)
X-Webhook-Signature	HMAC-SHA256 signature (custom webhooks with a secret only)

If the endpoint returns a non-2xx status code, the delivery is marked as failed. BadgerPanel retries failed deliveries up to 3 times with exponential backoff.

---

Testing a Webhook

After creating a webhook, use the Test button on the webhook detail page. This sends a test event to the configured URL so you can verify that the endpoint is reachable and the message format is correct. The test payload includes a test event type with sample data.

---

Webhook Logs

Each webhook maintains a delivery log. View it from the webhook detail page. Each log entry shows:

Field	Description
Event	The event type that triggered the delivery
Status	The HTTP status code returned, or an error message if the request failed
Triggered At	Timestamp of the delivery attempt
Response Time	How long the endpoint took to respond

Use the logs to diagnose delivery failures and verify that events are being processed correctly.

---

Editing and Deleting Webhooks

To edit a webhook, navigate to Admin > Webhooks > [webhook] and modify any field. To delete a webhook, click Delete on the webhook detail page. Deleting a webhook removes it and all its delivery logs permanently.

---

Next Steps

• Support & CRM - ticket system integration
• Billing - billing events for webhook triggers