Webhooks

Webhooks allow external services to send messages to Chirp channels via HTTP POST. This is ideal for integrating with monitoring tools, CI/CD pipelines, alerting systems, and automation platforms.

Creating a Webhook

1. Navigate to Channel Settings

Go to the channel where you want to receive webhook messages and click the Settings gear icon.

2. Open the Webhooks Tab

Click on the Webhooks tab in the channel settings panel.

3. Create a New Webhook

• Click Create Webhook
• Give your webhook a descriptive name (e.g., "GitHub Deployments", "Server Alerts")
• Optionally upload an avatar image
• Configure override settings (see below)
• Click Create

4. Copy the Webhook URL

After creation, your webhook URL will be displayed:

https://your-chirp-instance.com/api/webhooks/{TOKEN}/execute

Important: Keep your webhook token secret! Anyone with the URL can post messages to the channel.

---

Webhook URL Format

POST https://your-domain.com/api/webhooks/{TOKEN}/execute

The {TOKEN} is a 64-character unique identifier that authenticates the webhook. No additional authentication headers are required.

---

Payload Format

Basic Message

Send a simple message with a JSON payload:

{
  "content": "Deployment to production completed successfully!"
}

With Username Override

If the webhook allows username override, you can customize the sender name:

{
  "content": "Build #1234 passed",
  "username": "GitHub Actions"
}

With Avatar Override

If the webhook allows avatar override, you can customize the sender avatar:

{
  "content": "Server CPU usage above 90%",
  "username": "Datadog",
  "avatar_url": "https://example.com/datadog-icon.png"
}

---

Configuration Options

When creating or editing a webhook, you can configure:

Setting	Description
Name	Default display name for the webhook
Avatar	Default avatar image for the webhook
Allow Username Override	Allow external services to override the display name
Allow Avatar Override	Allow external services to override the avatar image

---

Example Integrations

GitHub

In your GitHub repository settings, add a webhook with:

https://your-chirp-instance.com/api/webhooks/{TOKEN}/execute

Content type: application/json

You'll need to configure GitHub to send the appropriate payload format, or use an intermediary service to transform GitHub's payload into Chirp's format.

GitLab

GitLab webhooks can be configured similarly. Use the generic webhook format and set the URL to your Chirp webhook endpoint.

Beszel (Server Monitoring)

For Beszel monitoring alerts, use the generic webhook format with custom field names:

generic://your-chirp-instance.com/api/webhooks/{TOKEN}/execute?template=json&messagekey=content

This tells Beszel to use content as the message field instead of the default message.

Jenkins

Add a POST build step with:

import groovy.json.JsonBuilder

def webhookUrl = 'https://your-chirp-instance.com/api/webhooks/{TOKEN}/execute'
def payload = new JsonBuilder([
    content: "Build ${env.BUILD_NUMBER} completed successfully!",
    username: "Jenkins CI"
]).toString()

sh """
    curl -X POST $webhookUrl \\
    -H 'Content-Type: application/json' \\
    -d '$payload'
"""

Custom Scripts

#!/bin/bash

WEBHOOK_URL="https://your-chirp-instance.com/api/webhooks/{TOKEN}/execute"

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Backup completed successfully!",
    "username": "Backup Script"
  }'

---

Security Best Practices

1. Keep tokens secret - Never commit webhook URLs to public repositories
2. Use dedicated channels - Create separate channels for different webhook sources
3. Monitor usage - Check webhook activity regularly
4. Disable unused webhooks - Delete or deactivate webhooks that are no longer needed
5. Limit overrides - Only enable username/avatar override if necessary

---

Limitations

Limitation	Value
Max content length	2000 characters
Supported methods	POST only
Content type	application/json
Authentication	Token in URL only

Webhooks do not support:

• File attachments
• Embeds or rich formatting
• Threaded messages
• Replies to existing messages
• Markdown (content is treated as plain text)

---

Troubleshooting

Webhook not delivering messages

1. Verify the webhook URL is correct
2. Check that the webhook is active in the webhook settings
3. Ensure the channel still exists and you have permission to post
4. Check that the payload JSON is valid

"Invalid content" error

• Ensure the content field is present and not empty
• Verify content is under 2000 characters
• Check that the JSON is properly formatted

Username/avatar not overriding

• Verify that Allow Username Override and/or Allow Avatar Override is enabled in the webhook settings
• Check that the field names are exactly username and avatar_url (case-sensitive)