Skip to main content

​
Overview

The Webhooks API allows you to manage Discord webhook integrations. All endpoints require authentication and follow RESTful conventions.

​
List All Webhooks

curl -X GET https://your-domain.com/webhooks \
  -H "Accept: application/json" \
  -H "X-CSRF-TOKEN: your-csrf-token" \
  --cookie "session-cookie"
GET /webhooks Retrieves all webhooks owned by or shared with the authenticated user.

​
Query Parameters

​
ownership
string
Filter by ownership: owned, shared, or all

​
Response

​
webhooks
array
Array of webhook objects
​
id
integer
Unique webhook identifier
​
name
string
Webhook display name
​
webhook_url
string
Discord webhook URL (masked in responses)
​
avatar_url
string
Webhook avatar URL
​
description
string
Webhook description
​
guild_id
string
Discord server (guild) ID
​
channel_id
string
Discord channel ID
​
tags
array
Array of tag strings
​
is_owner
boolean
Whether current user owns this webhook
​
permission_level
string
User’s permission: owner, edit, send, or view
​
message_history_count
integer
Total messages sent through this webhook
Response Example
{
  "webhooks": [
    {
      "id": 1,
      "name": "Server Updates",
      "webhook_url": "https://discord.com/api/webhooks/***",
      "avatar_url": "https://cdn.discordapp.com/avatars/...",
      "description": "Automated server status updates",
      "guild_id": "123456789",
      "channel_id": "987654321",
      "tags": ["production", "alerts"],
      "is_owner": true,
      "permission_level": "owner",
      "message_history_count": 42,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ]
}

​
Create Webhook

POST /webhooks Creates a new webhook after validating it with Discord’s API.

​
Request Body

​
webhook_url
string
required
Discord webhook URL. Must start with https://discord.com/api/webhooks/ or https://discordapp.com/api/webhooks/
​
name
string
Webhook name (auto-filled from Discord if not provided)
​
avatar_url
string
Avatar URL (auto-filled from Discord if not provided)
​
description
string
Webhook description (max 1000 characters)
​
tags
array
Array of tag strings (max 50 characters each)
{
  "webhook_url": "https://discord.com/api/webhooks/123456789/abcdefg",
  "name": "Production Alerts",
  "description": "Critical production notifications",
  "tags": ["production", "alerts", "critical"]
}

​
Response

Returns 302 redirect to /webhooks with success message.

​
Get Webhook Details

GET /webhooks/{id} Retrieve detailed information about a specific webhook.

​
Path Parameters

​
id
integer
required
Webhook ID

​
Response

​
webhook
object
Webhook details with statistics
​
stats
object
Message statistics
​
total
integer
Total messages sent
​
success
integer
Successful messages
​
error
integer
Failed messages
​
recent
integer
Messages in last 7 days
Response
{
  "webhook": {
    "id": 1,
    "name": "Server Updates",
    "webhook_url": "https://discord.com/api/webhooks/***",
    "description": "Automated server updates",
    "guild_id": "123456789",
    "channel_id": "987654321",
    "is_owner": true,
    "permission_level": "owner",
    "message_history": [
      // Recent 10 messages
    ]
  },
  "stats": {
    "total": 150,
    "success": 148,
    "error": 2,
    "recent": 25
  }
}

​
Update Webhook

PUT/PATCH /webhooks/{id} Update webhook details. If webhook URL is changed, it will be validated with Discord.

​
Path Parameters

​
id
integer
required
Webhook ID

​
Request Body

​
webhook_url
string
required
Discord webhook URL
​
name
string
Webhook name
​
avatar_url
string
Avatar URL
​
description
string
Description (max 1000 characters)
​
tags
array
Array of tags
{
  "webhook_url": "https://discord.com/api/webhooks/123456789/abcdefg",
  "name": "Updated Name",
  "description": "Updated description",
  "tags": ["updated", "production"]
}

​
Delete Webhook

DELETE /webhooks/{id} Permanently delete a webhook. Only the owner can delete a webhook.

​
Path Parameters

​
id
integer
required
Webhook ID

​
Response

Returns 302 redirect to /webhooks with success message.

​
Validate Webhook URL

POST /webhooks/validate Validate a Discord webhook URL with Discord’s API before saving.

​
Request Body

​
webhook_url
string
required
Discord webhook URL to validate
{
  "webhook_url": "https://discord.com/api/webhooks/123456789/abcdefg"
}

​
Response

​
success
boolean
Whether validation succeeded
​
data
object
Discord webhook metadata
​
name
string
Webhook name from Discord
​
avatar_url
string
Webhook avatar URL from Discord
​
guild_id
string
Discord server ID
​
channel_id
string
Discord channel ID
Success Response
{
  "success": true,
  "data": {
    "name": "Captain Hook",
    "avatar_url": "https://cdn.discordapp.com/avatars/...",
    "guild_id": "123456789",
    "channel_id": "987654321"
  }
}
Error Response
{
  "success": false,
  "message": "Invalid Discord webhook URL or webhook no longer exists."
}

​
Get Message History

GET /webhooks/{id}/history Retrieve message history for a webhook with pagination.

​
Path Parameters

​
id
integer
required
Webhook ID

​
Query Parameters

​
page
integer
default:"1"
Page number

​
Response

​
messages
object
Paginated message history
​
data
array
Array of message objects
​
current_page
integer
Current page number
​
per_page
integer
Items per page (20)
​
total
integer
Total number of messages
Response
{
  "messages": {
    "data": [
      {
        "id": 1,
        "user_id": 1,
        "webhook_id": 1,
        "message_content": {
          "content": "Hello Discord!",
          "embeds": []
        },
        "status": "success",
        "sent_at": "2024-01-15T10:30:00.000000Z",
        "user": {
          "id": 1,
          "name": "John Doe"
        }
      }
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 150
  }
}

​
Authorization

Webhook operations require specific permissions:
OperationPermission Required
ListAny (shows owned + shared)
Viewview, send, edit, or owner
CreateAuthenticated user
Updateedit or owner
Deleteowner only
Sendsend, edit, or owner

​
Error Codes

CodeDescription
401Not authenticated
403Insufficient permissions
404Webhook not found
422Validation error (invalid Discord URL, etc.)

Build docs developers (and LLMs) love

Get started for freeTalk to us