Skip to main content

​
Webhook Resource

Webhooks allow external services to post messages to Fluxer channels without a bot account.

​
Webhook Object

​
Structure

​
id
Snowflake
required
Unique webhook identifier
​
type
integer
required
Webhook type (see Webhook Types)
​
guild_id
Snowflake | null
Guild ID where the webhook exists
​
channel_id
Snowflake | null
Channel ID where the webhook posts
​
user
User object | null
User who created the webhook
​
creator_id
Snowflake | null
ID of the creator user
​
name
string
required
Webhook display name (1-80 characters)
​
avatar_hash
string | null
Hash of the webhook’s avatar
​
token
string
Secure token for webhook authentication (only returned on creation)
​
application_id
Snowflake | null
Application ID (for application webhooks)
​
version
integer
required
Version for optimistic concurrency control

​
Example Webhook

{
  "id": "666777888999000111",
  "type": 1,
  "guild_id": "987654321098765432",
  "channel_id": "444555666777888999",
  "user": {
    "id": "123456789012345678",
    "username": "fluxeruser",
    "discriminator": 1234,
    "avatar_hash": "a1b2c3d4e5f6"
  },
  "creator_id": "123456789012345678",
  "name": "GitHub Notifications",
  "avatar_hash": "webhook_avatar_hash",
  "token": "webhook_secret_token_here",
  "version": 1
}

​
Webhook Types

​
Creating Webhooks

Webhooks are created in a channel and post messages to that channel. The creator needs MANAGE_WEBHOOKS permission.

​
Webhook Token

The webhook token is only returned when creating or retrieving the webhook with proper permissions. It should be kept secure:
  • Never commit tokens to version control
  • Rotate tokens if compromised
  • Use environment variables or secure storage

​
Executing Webhooks

Webhooks can post messages using their token without requiring a bot account or OAuth2.

​
Request Format

POST /api/v1/webhooks/{webhook_id}/{webhook_token}
​
content
string
Message content (max 2000 characters for webhooks)
​
username
string
Override the webhook’s default username
​
avatar_url
string
Override the webhook’s default avatar (URL)
​
embeds
array
Array of embed objects (max 10)
​
allowed_mentions
object
Control which mentions are allowed
​
flags
integer
Message flags (e.g., suppress embeds)
​
wait
boolean
default:"false"
Wait for message to be created and return it
​
thread_id
Snowflake
Send message to a specific thread

​
Example Request

{
  "content": "New commit pushed to main branch!",
  "username": "GitHub Bot",
  "avatar_url": "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png",
  "embeds": [
    {
      "title": "Commit: Fix bug in message handling",
      "url": "https://github.com/org/repo/commit/abc123",
      "description": "Fixed an issue where messages weren't properly validated",
      "color": 3447003,
      "author": {
        "name": "octocat",
        "icon_url": "https://github.com/octocat.png"
      },
      "timestamp": "2026-03-04T12:00:00.000Z"
    }
  ]
}

​
Webhook vs Bot

​
When to use Webhooks:

  • Simple one-way notifications
  • External service integrations (CI/CD, monitoring)
  • No need for user interactions
  • Lower setup complexity

​
When to use Bots:

  • Two-way interactions required
  • Need to read messages or react
  • Complex command handling
  • Guild-specific configurations
  • Require permissions beyond posting

​
Rate Limits

Webhooks have separate rate limits from user accounts:
  • Per-webhook: 30 requests per minute
  • Global: 50 requests per second
Exceeding rate limits returns 429 Too Many Requests with a Retry-After header.

​
Endpoints

​
Create Webhook

POST /api/v1/channels/{channel_id}/webhooks
Create a webhook in a channel. Requires MANAGE_WEBHOOKS permission.
​
name
string
required
Webhook name (1-80 characters)
​
avatar
string | null
Base64 encoded image data for avatar

​
Get Channel Webhooks

GET /api/v1/channels/{channel_id}/webhooks
Returns all webhooks in a channel. Requires MANAGE_WEBHOOKS permission.

​
Get Guild Webhooks

GET /api/v1/guilds/{guild_id}/webhooks
Returns all webhooks in the guild. Requires MANAGE_WEBHOOKS permission.

​
Get Webhook

GET /api/v1/webhooks/{webhook_id}
Returns webhook information. Requires MANAGE_WEBHOOKS permission or webhook token.

​
Get Webhook with Token

GET /api/v1/webhooks/{webhook_id}/{webhook_token}
Returns webhook information using the webhook token (no authentication required).

​
Modify Webhook

PATCH /api/v1/webhooks/{webhook_id}
Modify a webhook. Requires MANAGE_WEBHOOKS permission.
​
name
string
New webhook name
​
avatar
string | null
New avatar (base64 encoded) or null to remove
​
channel_id
Snowflake
Move webhook to a different channel

​
Modify Webhook with Token

PATCH /api/v1/webhooks/{webhook_id}/{webhook_token}
Modify a webhook using the token (no authentication required).

​
Delete Webhook

DELETE /api/v1/webhooks/{webhook_id}
Delete a webhook. Requires MANAGE_WEBHOOKS permission.

​
Delete Webhook with Token

DELETE /api/v1/webhooks/{webhook_id}/{webhook_token}
Delete a webhook using the token (no authentication required).

​
Execute Webhook

POST /api/v1/webhooks/{webhook_id}/{webhook_token}
Execute a webhook and post a message.

​
Execute Slack-Compatible Webhook

POST /api/v1/webhooks/{webhook_id}/{webhook_token}/slack
Execute a webhook using Slack-compatible JSON format.

​
Execute GitHub-Compatible Webhook

POST /api/v1/webhooks/{webhook_id}/{webhook_token}/github
Execute a webhook using GitHub webhook format.

​
Get Webhook Message

GET /api/v1/webhooks/{webhook_id}/{webhook_token}/messages/{message_id}
Retrieve a message posted by the webhook.

​
Edit Webhook Message

PATCH /api/v1/webhooks/{webhook_id}/{webhook_token}/messages/{message_id}
Edit a message posted by the webhook.

​
Delete Webhook Message

DELETE /api/v1/webhooks/{webhook_id}/{webhook_token}/messages/{message_id}
Delete a message posted by the webhook.

​
Security Best Practices

  1. Keep tokens secure - Never expose webhook tokens publicly
  2. Validate sources - Verify requests come from expected sources
  3. Use HTTPS - Always use secure connections
  4. Rotate tokens - Regenerate tokens periodically or when compromised
  5. Limit permissions - Only grant webhook creation to trusted users
  6. Monitor usage - Track webhook activity for suspicious patterns

​
Common Use Cases

​
CI/CD Notifications

{
  "content": "Build completed successfully!",
  "embeds": [{
    "title": "Build #123",
    "color": 3066993,
    "fields": [
      {"name": "Status", "value": "✅ Passed", "inline": true},
      {"name": "Duration", "value": "2m 34s", "inline": true}
    ]
  }]
}

​
Monitoring Alerts

{
  "content": "@here Server alert!",
  "username": "Monitoring System",
  "embeds": [{
    "title": "🚨 High CPU Usage",
    "description": "Server CPU usage exceeded 90%",
    "color": 15158332,
    "timestamp": "2026-03-04T12:00:00.000Z"
  }]
}

​
RSS/News Feeds

{
  "embeds": [{
    "title": "New Article: Understanding Webhooks",
    "url": "https://blog.fluxer.chat/webhooks",
    "description": "Learn how to integrate external services...",
    "thumbnail": {
      "url": "https://blog.fluxer.chat/thumbnail.jpg"
    }
  }]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us