Webhooks
Create, update, execute and delete the Discord webhooks a project owns, with a project API key.
Discord webhook creation and management, authenticated with a project API key
List webhooks for a project
/api/projects/{projectId}/webhooksReturns the webhooks owned by the requesting project. Channel and server names are resolved from the bot cache and may be null.
Authentication: Project API key (X-API-Key header)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | Project ID (must be the requesting project) |
serverId | query | string | no | Filter by Discord server ID. The project must have access to that server. |
limit | query | number | no | Max number of webhooks (1-100) Default: 50. |
offset | query | number | no | Pagination offset Default: 0. |
Responses
| Status | Description | Body |
|---|---|---|
200 | List of webhooks. | WebhookListResponseDto |
400 | Invalid query parameters. | |
401 | Missing or invalid API key. | |
403 | The serverId filter names a server the project cannot access. | |
404 | Project not found for this API key. |
Open in Swagger (opens in a new tab)
Create a webhook for a channel
/api/servers/{serverId}/channels/{channelId}/webhooksCreates a Discord webhook in the channel and stores it for the project. The webhook URL and token are encrypted at rest and never returned.
Authentication: Project API key (X-API-Key header)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord server ID |
channelId | path | string | yes | Discord channel ID |
Request body (JSON, required): CreateWebhookDto schema.
Responses
| Status | Description | Body |
|---|---|---|
201 | Webhook created. | WebhookCreatedResponseDto |
400 | Invalid name or avatar. | |
401 | Missing or invalid API key. | |
403 | Project does not have MANAGE_WEBHOOKS operation on this server. | |
404 | Channel does not exist or bot lacks access. | |
409 | Project webhook limit reached. | |
502 | Discord API error. |
Open in Swagger (opens in a new tab)
Get webhook details
/api/webhooks/{webhookId}Returns webhook details. The webhook must belong to the requesting project.
Authentication: Project API key (X-API-Key header)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string | yes | Webhook ID |
Responses
| Status | Description | Body |
|---|---|---|
200 | Webhook details. | WebhookDetailResponseDto |
401 | Missing or invalid API key. | |
404 | Webhook not found for this project. |
Open in Swagger (opens in a new tab)
Update webhook settings
/api/webhooks/{webhookId}Updates the webhook name and/or avatar on Discord, then in storage. The webhook must belong to the requesting project.
Authentication: Project API key (X-API-Key header)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string | yes | Webhook ID |
Request body (JSON, required): UpdateWebhookDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | Updated webhook. | WebhookDetailResponseDto |
400 | Invalid name or avatar. | |
401 | Missing or invalid API key. | |
404 | Webhook not found for this project. | |
502 | Discord API error. |
Open in Swagger (opens in a new tab)
Delete a webhook
/api/webhooks/{webhookId}Deletes the webhook on Discord and removes it from storage. The webhook must belong to the requesting project.
Authentication: Project API key (X-API-Key header)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string | yes | Webhook ID |
Responses
| Status | Description | Body |
|---|---|---|
204 | Webhook deleted. | |
401 | Missing or invalid API key. | |
404 | Webhook not found for this project. | |
502 | Discord API error. |
Open in Swagger (opens in a new tab)
Execute a webhook
/api/webhooks/{webhookId}/executeSends a message through a stored Discord webhook. The webhook must belong to the requesting project.
Authentication: Project API key (X-API-Key header)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string | yes | Webhook ID |
Request body (JSON, required): ExecuteWebhookDto schema.
Responses
| Status | Description | Body |
|---|---|---|
204 | Webhook executed. | |
400 | Message content and embeds are both empty or invalid. | |
401 | Missing or invalid API key. | |
404 | Webhook not found for this project. | |
429 | Execution limit exceeded for this project. | |
502 | Discord rejected every attempt. |
Open in Swagger (opens in a new tab)
Schemas
CreateWebhookDto schema
| Field | Type | Required | Description |
|---|---|---|---|
avatar | string | no | Base64-encoded avatar image, decoded size max 256KB. A base64 data URI is also accepted. |
name | string | yes | Webhook name (2-80 chars) |
EmbedAuthorDto schema
| Field | Type | Required | Description |
|---|---|---|---|
icon_url | string (uri) | no | Author icon URL |
name | string | yes | Author name |
url | string (uri) | no | Author URL |
EmbedDto schema
| Field | Type | Required | Description |
|---|---|---|---|
author | EmbedAuthorDto | no | Embed author |
color | number | no | Color as decimal integer (0-16777215) |
description | string | no | Embed description |
footer | EmbedFooterDto | no | Embed footer |
image | EmbedImageDto | no | Embed image |
thumbnail | EmbedThumbnailDto | no | Embed thumbnail |
title | string | no | Embed title |
url | string (uri) | no | Embed URL |
EmbedFooterDto schema
| Field | Type | Required | Description |
|---|---|---|---|
icon_url | string (uri) | no | Footer icon URL |
text | string | yes | Footer text |
EmbedImageDto schema
| Field | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | URL of the image |
EmbedThumbnailDto schema
| Field | Type | Required | Description |
|---|---|---|---|
url | string (uri) | yes | URL of the thumbnail |
ExecuteWebhookDto schema
| Field | Type | Required | Description |
|---|---|---|---|
avatar_url | string (uri) | no | Avatar used for this message |
content | string | no | Message content, optional when embeds are present |
embeds | array of EmbedDto | no | Embed objects |
username | string | no | Name used for this message |
UpdateWebhookDto schema
| Field | Type | Required | Description |
|---|---|---|---|
avatar | string or null | no | Base64-encoded avatar image (decoded size max 256KB), or null to remove the avatar. |
name | string | no | Webhook name (2-80 chars) |
WebhookCreatedResponseDto schema
| Field | Type | Required | Description |
|---|---|---|---|
channelId | string | yes | Discord channel ID |
createdAt | string | yes | ISO 8601 creation timestamp |
id | string | yes | Webhook ID |
name | string | yes | Webhook name |
projectId | string | yes | Owning project ID |
serverId | string | yes | Discord server ID |
usageCount | number | yes | Number of executions |
WebhookDetailResponseDto schema
| Field | Type | Required | Description |
|---|---|---|---|
avatar | string or null | yes | Discord avatar hash |
channelId | string | yes | Discord channel ID |
channelName | string or null | yes | Channel name from the bot cache |
createdAt | string | yes | ISO 8601 creation timestamp |
id | string | yes | Webhook ID |
lastUsedAt | string or null | yes | ISO 8601 timestamp of the last execution |
name | string | yes | Webhook name |
serverId | string | yes | Discord server ID |
serverName | string or null | yes | Server name from the bot cache |
usageCount | number | yes | Number of executions |
WebhookListResponseDto schema
| Field | Type | Required | Description |
|---|---|---|---|
limit | number | yes | Applied limit |
offset | number | yes | Applied offset |
total | number | yes | Total webhooks matching the filter |
webhooks | array of WebhookSummaryDto | yes |
WebhookSummaryDto schema
| Field | Type | Required | Description |
|---|---|---|---|
channelId | string | yes | Discord channel ID |
channelName | string or null | yes | Channel name from the bot cache |
createdAt | string | yes | ISO 8601 creation timestamp |
id | string | yes | Webhook ID |
lastUsedAt | string or null | yes | ISO 8601 timestamp of the last execution |
name | string | yes | Webhook name |
serverId | string | yes | Discord server ID |
serverName | string or null | yes | Server name from the bot cache |
usageCount | number | yes | Number of executions |
Source: apps/api/openapi.json.