Channel Webhooks Help Guide

Getting Started

Webhooks allow external services like Jenkins, GitHub, GitLab, monitoring systems, or custom bots to send messages directly to your BitoLink channels. This enables automated notifications for builds, deployments, alerts, and more.

What Can You Do With Webhooks?

Step 1: Create a Webhook

Step 2: Copy the Webhook URL

After creating the webhook, you'll see a unique Webhook URL. This URL is used by external services to send messages.

Step 3: Configure Your External Service

Use the webhook URL in your CI/CD pipeline, monitoring system, or any service that supports webhooks.

Message Format

When sending messages via webhook, you can include plain text, user mentions, and emojis.

Plain Text

Simply send your message as plain text. Line breaks are preserved.

Build #295 completed successfully!
Branch: main
Status: Passed

Mentioning Users

To mention users in your webhook messages, use their email address:

When you mention a user:

• Their name appears as a clickable mention in the channel
• They receive a notification
• They can click on their name to see their profile

Build failed!
Please review: <@developer@company.com>
CC: @team-lead@company.com

Using Emojis

To include emojis in your webhook messages, insert the actual emoji character directly into your text.

🚀 Build Status: SUCCESS ✅
📌 Branch: main
🌐 Deployed to production

👉 Please verify the deployment.

Trigger Webhook

To send a message via webhook, make a POST request to your webhook URL with JSON body.

Webhook URL

Your webhook URL looks like:

https://your-server.com/api/v1/hooks/YOUR_WEBHOOK_TOKEN

Request Body

Send a JSON object with the following fields:

Example: Simple Message

{
  "text": "Hello from webhook!"
}

Example: With Line Breaks

Use \n to create new lines in your message:

{
  "text": "Build Completed!\n\nProject: MyApp\nStatus: SUCCESS\nBuild Number: 142"
}

This will display as:

Build Completed!

Project: MyApp
Status: SUCCESS
Build Number: 142

Example: With Mentions and Custom Username

{
  "text": "Hi <@developer@company.com>, <@manager@company.com>,\n\nProject: PayBito Admin\nBuild Status: SUCCESS\nBuild Number: 305\nCommit: 3a374b9e\n\nPlease check your email for details.",
  "username": "Jenkins CI Bot"
}

Example: Full Message with Custom Avatar

{
  "text": "Deployment Complete!\n\nEnvironment: Production\nVersion: v2.1.0\nDeployed by: <@devops@company.com>\n\nAll services are healthy.",
  "username": "GitHub Actions",
  "icon_url": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png"
}

Code Examples

Here are examples of how to trigger webhooks using different programming languages and tools.

Using cURL

curl -X POST https://your-server.com/api/v1/hooks/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Build Status: SUCCESS\n\nProject: MyApp\nBranch: main\n\nCC: <@team@company.com>",
    "username": "Jenkins Bot"
  }'

Using JavaScript/Node.js

fetch('https://your-server.com/api/v1/hooks/YOUR_TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    text: 'Deployment complete!\n\nEnvironment: Production\nStatus: Healthy',
    username: 'Deploy Bot'
  })
});

Using Python

import requests

webhook_url = 'https://your-server.com/api/v1/hooks/YOUR_TOKEN'

payload = {
    'text': 'Build Complete!\n\nProject: MyApp\nStatus: SUCCESS',
    'username': 'Python Bot'
}

response = requests.post(webhook_url, json=payload)
print(response.status_code)

Using PHP

<?php
$webhookUrl = 'https://your-server.com/api/v1/hooks/YOUR_TOKEN';

$payload = [
    'text' => "Alert!\n\nServer: Production\nStatus: Critical",
    'username' => 'PHP Monitor'
];

$ch = curl_init($webhookUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>

Common Use Cases

Here are some popular ways to use webhooks in your workflow.

CI/CD Notifications

Send build status updates to keep your team informed:

• Build started/completed notifications
• Test results summary
• Deployment status
• Failed build alerts with assignee mentions

Monitoring Alerts

Receive real-time alerts from your monitoring systems:

• Server health alerts
• Error rate spikes
• Resource usage warnings
• Downtime notifications

Custom Integrations

Build your own integrations:

• Form submission notifications
• Customer support ticket alerts
• Scheduled reports
• Any event-based notifications

Managing Webhooks

Learn how to view, regenerate, and delete webhooks.

View Webhooks

Regenerate Token

Delete a Webhook

Best Practices

Follow these recommendations to get the most out of webhooks.

Security Tips

Keep your webhooks secure with these important guidelines.

Troubleshooting

Common issues and how to resolve them.

Need Help?

If you're having issues with webhooks: