Inbound Webhooks (Admin)
Create and manage inbound webhooks: schemas and previews, reader roles, settings, signing secrets, docs and deletion.
List inbound webhooks
/api/admin/inbound-webhooksAuthentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | query | string | no |
Responses
| Status | Description | Body |
|---|---|---|
200 | Webhooks, newest first. |
Open in Swagger (opens in a new tab)
Create an inbound webhook
/api/admin/inbound-webhooksThe schema is validated up front. Name the Discord roles that may read submissions, or omit allowedRoleIds to use the default reader roles (MC Executive unless changed in the settings). At least one role must result - unlike project_roles, an empty role set means nobody, not everybody. The signing secret is returned exactly once.
Authentication: Admin session token (Authorization: Bearer <token>)
Request body (JSON, required): CreateInboundWebhookDto schema.
Responses
| Status | Description | Body |
|---|---|---|
201 | Created; signingSecret returned once. | |
400 | Invalid schema, or unknown/foreign roles. | |
409 | Slug already used by this project. |
Open in Swagger (opens in a new tab)
Check a schema and preview its docs
/api/admin/inbound-webhooks/schema/previewRuns the same validator as create without saving anything, for the admin schema editor. An invalid schema is a normal 200 with ok: false and every problem with its path; a valid one returns the generated developer docs and an example payload, with placeholders for what only exists once the webhook is saved (its ID and readers). Nothing is stored or audited.
Authentication: Admin session token (Authorization: Bearer <token>)
Request body (JSON, required): PreviewInboundWebhookSchemaDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | { ok: false, errors: [{ path, code, message }] } or { ok: true, markdown, examplePayload }. | |
400 | The request itself is malformed. |
Open in Swagger (opens in a new tab)
Get the inbound webhook settings
/api/admin/inbound-webhooks/settingsThe default reader roles new webhooks get when their creator names none. source is environment until the setting is first saved, when it falls back to the executive role.
Authentication: Admin session token (Authorization: Bearer <token>)
Responses
| Status | Description | Body |
|---|---|---|
200 | The effective settings. |
Open in Swagger (opens in a new tab)
Replace the default reader roles
/api/admin/inbound-webhooks/settingsApplies to webhooks created afterwards; existing webhooks keep their roles. An empty list means no defaults.
Authentication: Admin session token (Authorization: Bearer <token>)
Request body (JSON, required): UpdateInboundWebhookSettingsDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | The settings after the change. | |
400 | Unknown role IDs. |
Open in Swagger (opens in a new tab)
Get one inbound webhook
/api/admin/inbound-webhooks/{id}Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
200 | object | |
404 | No such webhook. |
Open in Swagger (opens in a new tab)
Update an inbound webhook
/api/admin/inbound-webhooks/{id}Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Request body (JSON, required): UpdateInboundWebhookDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | object | |
400 | Invalid schema. |
Open in Swagger (opens in a new tab)
Delete an inbound webhook and all its submissions
/api/admin/inbound-webhooks/{id}Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
204 | Deleted. |
Open in Swagger (opens in a new tab)
Export developer documentation for this webhook
/api/admin/inbound-webhooks/{id}/docsGenerated from the live schema, so it can never drift from what the validator enforces. Markdown is a ready-to-share integration guide (endpoint, auth, signing code in JS and Python, every field with its constraints, an example payload, the full error table, and who may read submissions). OpenAPI is an importable 3.1 spec for Postman, Insomnia or client codegen.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | |
format | query | "markdown" or "openapi" | no | Defaults to markdown. |
download | query | string | no | Set to "true" to receive it as a file attachment. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The rendered documentation. | |
404 | No such webhook. |
Open in Swagger (opens in a new tab)
List the Discord roles permitted to read submissions
/api/admin/inbound-webhooks/{id}/rolesAuthentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
200 |
Open in Swagger (opens in a new tab)
Replace the read-access role grants
/api/admin/inbound-webhooks/{id}/rolesThe set can never be emptied - removing the last role is a deletion of the webhook.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Request body (JSON, required): SetAllowedRolesDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | ||
400 | Empty set, or unknown/foreign roles. |
Open in Swagger (opens in a new tab)
Rotate the signing secret
/api/admin/inbound-webhooks/{id}/rotate-secretReturned exactly once. Previously issued signatures stop verifying.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Status | Description | Body |
|---|---|---|
201 |
Open in Swagger (opens in a new tab)
Schemas
CreateInboundWebhookDto schema
| Field | Type | Required | Description |
|---|---|---|---|
acceptedOrigins | array of string | no | Origins permitted to call this webhook. Empty = no check. |
allowRoleInheritance | boolean | no | When true, a member can also read this webhook's submissions through role inheritance: a role they hold on the main server that is the source of an enabled inheritance rule covering the server of a granted role counts as that granted role, matched by role name. Off by default: data access should be explicit. Default: false. |
allowedRoleIds | array of string | no | Discord role IDs permitted to READ submissions. When omitted, the configured default reader roles are used (MC Executive unless changed in the inbound webhook settings); when given, exactly these roles are used. At least one role must result. |
name | string | yes | |
projectId | string | yes | The project this webhook belongs to. |
rejectUnknownFields | boolean | no | Default: true. |
requireSignature | boolean | no | Default: true. |
schema | object | yes | The shape of what callers send. Either steps (a multi-step form; the payload is keyed by step) or fields (a flat payload, for an event or any non-form data), not both. Validated by the Layer-1 schema validator. |
slug | string | yes | URL-safe identifier, unique within the project. |
PreviewInboundWebhookSchemaDto schema
| Field | Type | Required | Description |
|---|---|---|---|
acceptedOrigins | array of string | no | Origins the docs list as permitted. Empty = any origin. |
name | string | no | Shown as the title of the generated docs. |
rejectUnknownFields | boolean | no | Whether the docs say unknown fields are rejected. Default: true. |
requireSignature | boolean | no | Whether the docs describe request signing. Default: true. |
schema | object | yes | Either steps or flat fields, not both; checked by the same validator that create uses. |
SetAllowedRolesDto schema
| Field | Type | Required | Description |
|---|---|---|---|
roleIds | array of string | yes |
UpdateInboundWebhookDto schema
| Field | Type | Required | Description |
|---|---|---|---|
acceptedOrigins | array of string | no | |
allowRoleInheritance | boolean | no | Let role inheritance rules grant read access to this webhook. See the create request for the rule. |
isActive | boolean | no | |
name | string | no | |
rejectUnknownFields | boolean | no | |
requireSignature | boolean | no | |
schema | object | no | Either steps or flat fields, not both; re-validated on update. |
UpdateInboundWebhookSettingsDto schema
| Field | Type | Required | Description |
|---|---|---|---|
defaultReaderRoleIds | array of string | yes | Discord role IDs given read access to every NEW inbound webhook whose creator names no roles. An empty list means no defaults. Existing webhooks keep the roles they already have. |
Source: apps/api/openapi.json.