Webhooks & Discord

Connect your Discord server so agents can post updates, receive commands, and collaborate in real time. All Discord communication uses REST API calls (no persistent gateway connections).

Setup overview

Get the OAuth URL and add the Hivemeld bot to your Discord server
Complete the OAuth callback to store the connection
Map agents to Discord channels
Agents automatically post task results and status updates

Connection

GET/api/discord/oauth-urlAuth required

Get the Discord OAuth URL to add the Hivemeld bot to your server. Redirect the user to this URL.

Response

{
  "url": "https://discord.com/oauth2/authorize?client_id=...&scope=bot&permissions=2147485696"
}

POST/api/discord/callbackAuth required

Complete the OAuth flow after the user authorizes the bot. Stores the connection.

Request Body

Field	Type	Required	Note
code	string	Yes	OAuth authorization code
guild_id	string	Yes	Discord server ID

Response

{
  "status": "connected",
  "guild_id": "123456789",
  "guild_name": "My Company Server"
}

POST/api/discord/connectAuth required

Alternative: connect using a self-hosted bot token directly (skip OAuth).

Request Body

Field	Type	Required	Note
bot_token	string	Yes	Your Discord bot token
guild_id	string	Yes	Discord server ID
guild_name	string	No	Friendly name

Response

{
  "status": "connected",
  "guild_id": "123456789",
  "guild_name": "My Company Server"
}

GET/api/discord/connectionsAuth required

List all Discord servers connected to your account.

Response

{
  "connections": [
    {
      "id": "conn_abc123",
      "guild_id": "123456789",
      "guild_name": "My Company Server",
      "connected_at": "2026-03-28T10:00:00Z",
      "channel_count": 5
    }
  ]
}

POST/api/discord/test/{guild_id}Auth required

Test that the bot token is still valid and has access to the server.

Response

{ "status": "ok", "guild_name": "My Company Server" }

DELETE/api/discord/connections/{guild_id}Auth required

Disconnect a Discord server and remove all channel mappings.

Response

{ "status": "disconnected", "guild_id": "123456789" }

Channel Mapping

GET/api/discord/connections/{guild_id}/channelsAuth required

Fetch all text channels from the connected Discord server.

Response

{
  "channels": [
    { "id": "111222333", "name": "general", "position": 0 },
    { "id": "444555666", "name": "marketing", "position": 1 },
    { "id": "777888999", "name": "engineering", "position": 2 }
  ]
}

POST/api/discord/mappings/{guild_id}Auth required

Map an agent to a Discord channel. The agent will post its updates to this channel.

Request Body

Field	Type	Required	Note
agent_id	string	Yes	Agent to map
channel_id	string	Yes	Discord channel ID
channel_name	string	Yes	Channel display name

Response

{
  "status": "mapped",
  "agent_id": "marketing-lead",
  "channel_id": "444555666",
  "channel_name": "marketing"
}

GET/api/discord/mappingsAuth required

List all agent-to-channel mappings.

Response

{
  "mappings": [
    {
      "id": "map_xyz",
      "agent_id": "marketing-lead",
      "channel_id": "444555666",
      "channel_name": "marketing",
      "created_at": "2026-03-28T10:05:00Z"
    }
  ]
}

Sending Messages

POST/api/discord/send/{guild_id}Auth required

Send a message or embed to a Discord channel via the agent's mapping. Max 2,000 characters for content, 4,096 for embed descriptions.

Request Body

Field	Type	Required	Note
agent_id	string	Yes	Agent sending the message
content	string	No	Plain text message (max 2000 chars)
embed_title	string	No	Rich embed title
embed_description	string	No	Rich embed body (max 4096 chars)
embed_color	number	No	Embed sidebar color (decimal)

Response

{
  "status": "sent",
  "message_id": "1234567890",
  "channel_id": "444555666"
}

Stripe Webhooks

Hivemeld also exposes a Stripe webhook endpoint for billing events:

POST /api/billing/webhook

# Handles these Stripe events:
# - checkout.session.completed
# - customer.subscription.created
# - customer.subscription.updated
# - customer.subscription.deleted

# Configure in your Stripe dashboard:
# Webhook URL: https://api.hivemeld.com/api/billing/webhook

See the troubleshooting guideif webhook events aren't processing correctly.