mirror of
https://github.com/mattermost/mattermost.git
synced 2026-02-03 20:40:00 -05:00
534 lines
18 KiB
YAML
534 lines
18 KiB
YAML
/api/v4/hooks/incoming:
|
|
post:
|
|
tags:
|
|
- webhooks
|
|
summary: Create an incoming webhook
|
|
description: |
|
|
Create an incoming webhook for a channel.
|
|
##### Permissions
|
|
`manage_webhooks` for the team the webhook is in.
|
|
|
|
`manage_others_incoming_webhooks` for the team the webhook is in if the user is different than the requester.
|
|
operationId: CreateIncomingWebhook
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- channel_id
|
|
properties:
|
|
channel_id:
|
|
type: string
|
|
description: The ID of a public channel or private group that receives
|
|
the webhook payloads.
|
|
user_id:
|
|
type: string
|
|
description: The ID of the owner of the webhook if different than the requester. Required for [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode).
|
|
display_name:
|
|
type: string
|
|
description: The display name for this incoming webhook
|
|
description:
|
|
type: string
|
|
description: The description for this incoming webhook
|
|
username:
|
|
type: string
|
|
description: The username this incoming webhook will post as.
|
|
icon_url:
|
|
type: string
|
|
description: The profile picture this incoming webhook will use when
|
|
posting.
|
|
channel_locked:
|
|
type: boolean
|
|
description: Whether the webhook is locked to the channel.
|
|
description: Incoming webhook to be created
|
|
required: true
|
|
responses:
|
|
"201":
|
|
description: Incoming webhook creation successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/IncomingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
get:
|
|
tags:
|
|
- webhooks
|
|
summary: List incoming webhooks
|
|
description: >
|
|
Get a page of a list of incoming webhooks. Optionally filter for a
|
|
specific team using query parameters.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for the system or `manage_webhooks` for the specific team.
|
|
operationId: GetIncomingWebhooks
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of hooks per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
- name: team_id
|
|
in: query
|
|
description: The ID of the team to get hooks for.
|
|
schema:
|
|
type: string
|
|
- name: include_total_count
|
|
description: >-
|
|
Appends a total count of returned hooks inside the response object - ex: `{ "incoming_webhooks": [], "total_count": 0 }`.
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
responses:
|
|
"200":
|
|
description: Incoming webhooks retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/IncomingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"/api/v4/hooks/incoming/{hook_id}":
|
|
get:
|
|
tags:
|
|
- webhooks
|
|
summary: Get an incoming webhook
|
|
description: >
|
|
Get an incoming webhook given the hook id.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
|
|
operationId: GetIncomingWebhook
|
|
parameters:
|
|
- name: hook_id
|
|
in: path
|
|
description: Incoming Webhook GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Webhook retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/IncomingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
delete:
|
|
tags:
|
|
- webhooks
|
|
summary: Delete an incoming webhook
|
|
description: >
|
|
Delete an incoming webhook given the hook id.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
|
|
operationId: DeleteIncomingWebhook
|
|
parameters:
|
|
- name: hook_id
|
|
in: path
|
|
description: Incoming webhook GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Webhook deletion successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
put:
|
|
tags:
|
|
- webhooks
|
|
summary: Update an incoming webhook
|
|
description: >
|
|
Update an incoming webhook given the hook id.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
|
|
operationId: UpdateIncomingWebhook
|
|
parameters:
|
|
- name: hook_id
|
|
in: path
|
|
description: Incoming Webhook GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- id
|
|
- channel_id
|
|
- display_name
|
|
- description
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Incoming webhook GUID
|
|
channel_id:
|
|
type: string
|
|
description: The ID of a public channel or private group that receives
|
|
the webhook payloads.
|
|
display_name:
|
|
type: string
|
|
description: The display name for this incoming webhook
|
|
description:
|
|
type: string
|
|
description: The description for this incoming webhook
|
|
username:
|
|
type: string
|
|
description: The username this incoming webhook will post as.
|
|
icon_url:
|
|
type: string
|
|
description: The profile picture this incoming webhook will use when
|
|
posting.
|
|
channel_locked:
|
|
type: boolean
|
|
description: Whether the webhook is locked to the channel.
|
|
description: Incoming webhook to be updated
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Webhook update successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/IncomingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
/api/v4/hooks/outgoing:
|
|
post:
|
|
tags:
|
|
- webhooks
|
|
summary: Create an outgoing webhook
|
|
description: |
|
|
Create an outgoing webhook for a team.
|
|
##### Permissions
|
|
`manage_webhooks` for the team the webhook is in.
|
|
|
|
`manage_others_outgoing_webhooks` for the team the webhook is in if the user is different than the requester.
|
|
operationId: CreateOutgoingWebhook
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- team_id
|
|
- display_name
|
|
- trigger_words
|
|
- callback_urls
|
|
properties:
|
|
team_id:
|
|
description: The ID of the team that the webhook watchs
|
|
type: string
|
|
channel_id:
|
|
description: The ID of a public channel that the webhook watchs
|
|
type: string
|
|
creator_id:
|
|
description: The ID of the owner of the webhook if different than the requester. Required in [local mode](https://docs.mattermost.com/administration/mmctl-cli-tool.html#local-mode).
|
|
type: string
|
|
description:
|
|
description: The description for this outgoing webhook
|
|
type: string
|
|
display_name:
|
|
description: The display name for this outgoing webhook
|
|
type: string
|
|
trigger_words:
|
|
description: List of words for the webhook to trigger on
|
|
type: array
|
|
items:
|
|
type: string
|
|
trigger_when:
|
|
description: When to trigger the webhook, `0` when a trigger word is
|
|
present at all and `1` if the message starts with a trigger
|
|
word
|
|
type: integer
|
|
callback_urls:
|
|
description: The URLs to POST the payloads to when the webhook is
|
|
triggered
|
|
type: array
|
|
items:
|
|
type: string
|
|
content_type:
|
|
description: The format to POST the data in, either `application/json` or
|
|
`application/x-www-form-urlencoded`
|
|
default: application/x-www-form-urlencoded
|
|
type: string
|
|
description: Outgoing webhook to be created
|
|
required: true
|
|
responses:
|
|
"201":
|
|
description: Outgoing webhook creation successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/OutgoingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
get:
|
|
tags:
|
|
- webhooks
|
|
summary: List outgoing webhooks
|
|
description: >
|
|
Get a page of a list of outgoing webhooks. Optionally filter for a
|
|
specific team or channel using query parameters.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for the system or `manage_webhooks` for the specific team/channel.
|
|
operationId: GetOutgoingWebhooks
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: The page to select.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: per_page
|
|
in: query
|
|
description: The number of hooks per page.
|
|
schema:
|
|
type: integer
|
|
default: 60
|
|
- name: team_id
|
|
in: query
|
|
description: The ID of the team to get hooks for.
|
|
schema:
|
|
type: string
|
|
- name: channel_id
|
|
in: query
|
|
description: The ID of the channel to get hooks for.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Outgoing webhooks retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/OutgoingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"/api/v4/hooks/outgoing/{hook_id}":
|
|
get:
|
|
tags:
|
|
- webhooks
|
|
summary: Get an outgoing webhook
|
|
description: >
|
|
Get an outgoing webhook given the hook id.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
|
|
operationId: GetOutgoingWebhook
|
|
parameters:
|
|
- name: hook_id
|
|
in: path
|
|
description: Outgoing webhook GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Outgoing webhook retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/OutgoingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
delete:
|
|
tags:
|
|
- webhooks
|
|
summary: Delete an outgoing webhook
|
|
description: >
|
|
Delete an outgoing webhook given the hook id.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
|
|
operationId: DeleteOutgoingWebhook
|
|
parameters:
|
|
- name: hook_id
|
|
in: path
|
|
description: Outgoing webhook GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Webhook deletion successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
put:
|
|
tags:
|
|
- webhooks
|
|
summary: Update an outgoing webhook
|
|
description: >
|
|
Update an outgoing webhook given the hook id.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
|
|
operationId: UpdateOutgoingWebhook
|
|
parameters:
|
|
- name: hook_id
|
|
in: path
|
|
description: outgoing Webhook GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- id
|
|
- channel_id
|
|
- display_name
|
|
- description
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Outgoing webhook GUID
|
|
channel_id:
|
|
type: string
|
|
description: The ID of a public channel or private group that receives
|
|
the webhook payloads.
|
|
display_name:
|
|
type: string
|
|
description: The display name for this incoming webhook
|
|
description:
|
|
type: string
|
|
description: The description for this incoming webhook
|
|
description: Outgoing webhook to be updated
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Webhook update successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/OutgoingWebhook"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"/api/v4/hooks/outgoing/{hook_id}/regen_token":
|
|
post:
|
|
tags:
|
|
- webhooks
|
|
summary: Regenerate the token for the outgoing webhook.
|
|
description: >
|
|
Regenerate the token for the outgoing webhook.
|
|
|
|
##### Permissions
|
|
|
|
`manage_webhooks` for system or `manage_webhooks` for the specific team or `manage_webhooks` for the channel.
|
|
operationId: RegenOutgoingHookToken
|
|
parameters:
|
|
- name: hook_id
|
|
in: path
|
|
description: Outgoing webhook GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Webhook token regenerate successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StatusOK"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|