Webhook Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Webhook integrations within Matterbridge serve as a critical mechanism for cross-protocol message synchronization, particularly for features like username and avatar spoofing. By utilizing webhooks instead of standard bot accounts for message delivery, Matterbridge can present messages on remote platforms using the original sender's profile information, creating a seamless "bridged" experience across services like Discord, Rocket.Chat, Slack, and Mattermost.
Sources: README.md:100-105, bridge/rocketchat/helpers.go:167-175
Discord Webhook Management
Matterbridge utilizes a specialized Transmitter component to manage Discord webhooks. This system handles the automated creation, discovery, and execution of webhooks across different guild channels to facilitate message bridging.
Transmitter Logic
The Transmitter maintains a mapping of channel IDs to specific discordgo.Webhook instances. It is designed to be "relevant" by only picking up webhooks previously created by the bot (matching the bot's ApplicationID).
The diagram above illustrates the decision logic within the Discord Transmitter when attempting to send a message via webhook.
Sources: bridge/discord/transmitter/transmitter.go:30-45, bridge/discord/transmitter/transmitter.go:138-155
Discovery and Permissions
The system can refresh webhooks for an entire guild or specific channels. It handles permission limitations gracefully:
- Guild-wide Permission: If the bot has the
Manage Webhookspermission for the guild, it loads all relevant hooks. - Channel-specific Fallback: If global permissions are missing, it attempts to fetch hooks for a provided list of specific channel IDs.
Sources: bridge/discord/transmitter/transmitter.go:94-118
| Error Constant | Description |
|---|---|
ErrWebhookNotFound | Returned when no valid webhook exists for a channel and autoCreate is false. |
ErrPermissionDenied | Returned if the bot lacks the 'Manage Webhooks' permission either globally or per-channel. |
Sources: bridge/discord/transmitter/transmitter.go:48-54
Rocket.Chat Integration
Rocket.Chat implementation uses both internal "matterhooks" and "rockethooks" to bridge data. It supports dual modes: sending via WebhookURL and receiving via WebhookBindAddress.
Webhook Execution Flow
When a message is sent via webhook in Rocket.Chat, Matterbridge wraps the payload into an OMessage (Outgoing Message) structure. This supports:
- Spoofing: Avatars and usernames are mapped from the source message to the webhook payload.
- File Handling: Since webhooks often do not support native file uploads, Matterbridge manually appends the file URL to the message text.
The sequence above shows how a Rocket.Chat bridge prepares a message and dispatches it through the matterhook utility.
Sources: bridge/rocketchat/helpers.go:167-200
Mattermost Webhook API
The project includes a comprehensive client-side implementation for Mattermost's webhook system. This allows for programmatic management of both Incoming (remote service to Mattermost) and Outgoing (Mattermost to remote service) webhooks.
API Capabilities
The Mattermost client (Client4) provides methods for full CRUD operations on webhooks, including team-specific filtering and token regeneration for outgoing hooks.
| Feature | Method | Endpoint Path |
|---|---|---|
| Create Incoming | CreateIncomingWebhook | /hooks/incoming |
| Create Outgoing | CreateOutgoingWebhook | /hooks/outgoing |
| List Team Hooks | GetIncomingWebhooksForTeam | /hooks/incoming?team_id=... |
| Rotate Token | RegenOutgoingHookToken | /hooks/outgoing/{id}/regen_token |
Sources: vendor/github.com/mattermost/mattermost-server/v6/model/client4.go:1385-1550
Webhook Data Models
The core data structures define how webhooks are stored and executed across the various protocol bindings.
Discord Webhook Structure
The Discord implementation uses the Webhook and WebhookParams structures from the discordgo library to define the payload for execution.
type Webhook struct {
ID string `json:"id"`
Type WebhookType `json:"type"`
GuildID string `json:"guild_id"`
ChannelID string `json:"channel_id"`
User *User `json:"user"`
Name string `json:"name"`
Avatar string `json:"avatar"`
Token string `json:"token"`
ApplicationID string `json:"application_id,omitempty"`
}
Sources: vendor/github.com/bwmarrin/discordgo/webhook.go:4-16
Execution Parameters
Execution allows for complex message formatting including:
- TTS: Text-to-speech support.
- Embeds: Rich media embeds.
- Components: Interactive UI elements (buttons, menus).
- AllowedMentions: Granular control over user/role notifications.
Sources: vendor/github.com/bwmarrin/discordgo/webhook.go:27-40
Webhook integrations are fundamental to Matterbridge's ability to maintain user identity across disparate chat protocols. By abstracting the management of these hooks into transmitters and protocol-specific helpers, the project ensures reliable message delivery even when standard bot permissions or features are restricted.