---

8.3 Using webhooks ¶

Webhooks in Telebugs enable real-time notifications to be sent to external services whenever specific events occur, such as a new error being reported, an error reoccurring, or the error frequency exceeding a set threshold. This feature allows integration with tools like Slack, Discord, or any custom endpoint that accepts HTTP POST requests.

Once webhooks are configured globally, individual projects can opt to use them or disable them via project settings. After setup, project-level rules dictate when notifications are sent to the configured webhook URLs.

You can configure webhooks to trigger under these conditions:

• Notify when a new error occurs for the first time.
• Notify when an error reoccurs after being resolved.
• Notify when error frequency exceeds a threshold (for example, more than 10 reports in 5 minutes).

Follow these steps to configure webhook notifications:

1. Open the menu in the top-right corner, click your profile name, and select Notification Configuration.
   
2. In the sidebar on the left, select Webhooks.
   
3. Click the Create Configuration button to begin adding a new webhook.
   
4. Complete the Add a new webhook form with details such as the webhook URL, name, template type, and template body, then click Save webhook to apply your settings.
   
5. Once saved, the webhook appears in the Configured webhooks section.
   
6. To verify the webhook, click the Test button next to it in the list. This sends a test payload to the specified URL.
   
7. To edit a webhook, click its name in the Configured webhooks section.
   
8. A popup appears, allowing you to modify the name and template body.
   
9. You can edit webhook URL and template body directly in the popup. Close the popup to save changes.
   
10. When a real error occurs, Telebugs sends a notification to the webhook URL based on the project settings, including details like the error message and a link to the error report.

Add a new webhook form ¶

The Add a new webhook form defines the settings for each webhook. Complete the fields as follows:

• Webhook URL: Enter the URL where notifications will be sent. This must be a publicly accessible endpoint capable of handling POST requests. This field is required.
• Name: Provide an optional name to identify the webhook later, such as a channel name (e.g., "#monitoring") or a description.
• Template: Select the payload template type from the dropdown: Slack, Discord, or Custom. Predefined templates auto-fill the template body, while "Custom" allows manual payload creation. This field is required.
• Template body: Define the JSON payload sent to the webhook URL. For predefined templates, this field pre-populates with a default structure. For custom templates, enter your own JSON using allowed interpolation keys. This field is required.

Webhook template body placeholders ¶

In the template body, use placeholders like {{key}} to insert dynamic values. The following keys are available:

• project_name: The project name (e.g., "Backend", "example.com").
• trigger: The event triggering the notification (e.g., "error", "reoccurrence", "error frequency exceeded").
• subject: A brief error description (e.g., "NoMethodError in ScoresController#create").
• culprit: The code location of the error (e.g., "ScoresController#create").
• location: The error’s location (e.g., file path or module).
• error_type: The error type (e.g., "NoMethodError", "Exception").
• error_message: The detailed error message (e.g., "undefined method ‘+’ for nil").
• project_url: The project’s URL in Telebugs (e.g., "https://tests.telebugs.com/projects/7").
• view_url: The URL to the error report (e.g., "https://tests.telebugs.com/errors/107").

Click the Help button next to the template body field for links to resources on webhooks, Slack, and Discord integration.

• Configuring Slack notifications
• Configuring Discord notifications
• Configuring custom webhooks