REST: Webhooks

Incoming and outgoing webhooks of a channel (Owner and Administrators only). Generated from mnema-talk v3.3.13 (cca4f0fdb723).

List a channel's outgoing webhooks

GET /api/admin/channels/{id}/outgoing-webhooks

Owner or Administrator only. Secrets are never listed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesChannel ID.

Responses

StatusMeaningBody
200Outgoing webhooks, oldest first.Outgoing[]
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this.ErrorResponse
404NOT_FOUND: the channel does not exist or is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Create an outgoing webhook

POST /api/admin/channels/{id}/outgoing-webhooks

Owner or Administrator only. The answer carries the signing secret, shown only once. Events of that channel are POSTed to the URL as signed JSON; see doc/webhooks.md. At most 10 per channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesChannel ID.

Request body (application/json, required): CreateOutgoingRequest

FieldTypeDescription
events (required)string[]
name (required)string
url (required)stringURL receives the events: http or https, public addresses only unless the operator allowed more (WEBHOOK_ALLOW_PRIVATE_TARGETS).

Responses

StatusMeaningBody
201Created.CreatedOutgoing
400Invalid input (INVALID_INPUT): bad name, URL (also: a forbidden address) or events.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the channel does not exist or is hidden from the caller.ErrorResponse
409CONFLICT: the maximum number of outgoing webhooks is reached.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
CreatedOutgoing
FieldTypeDescription
channel_id (required)string (uuid)ChannelID is the channel the webhook belongs to; it receives that channel's events only.
consecutive_failures (required)integer
created_at (required)string (date-time)
created_by (required)string | nullCreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing.
events (required)string[]Events are the subscribed event types (see doc/webhooks.md).
id (required)string (uuid)
last_attempt_at (required)string | null
last_error (required)string | nullLastError is a short code for the latest failure ("timeout", "blocked_address", "http_500", ...); null after a success.
last_status (required)integer | nullLastStatus is the HTTP status of the latest attempt (null: none yet, or no response).
last_success_at (required)string | null
name (required)string
secret (required)stringSecret signs every delivery (see X-Mnema-Signature in doc/webhooks.md).
status (required)stringStatus is "active", "disabled" (switched off by an administrator) or "auto_disabled" (switched off after repeated failures).
url (required)string
url_set_at (required)string (date-time)
url_set_by (required)string | nullURLSetBy and URLSetAt record who last set the URL and when, so stale webhooks are easy to spot. The URL receives the channel's events until an administrator changes or deletes the webhook.

List a channel's webhooks

GET /api/admin/channels/{id}/webhooks

Owner or Administrator only. The tokens are never listed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesChannel ID.

Responses

StatusMeaningBody
200Webhooks, oldest first.Webhook[]
400Invalid input (INVALID_INPUT): bad ID.ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this.ErrorResponse
404NOT_FOUND: the channel does not exist or is hidden from the caller.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Create a webhook

POST /api/admin/channels/{id}/webhooks

Owner or Administrator only. The webhook belongs to the channel and posts with exactly its settings (see the allow_* fields; defaults: everyone-mentions off, the rest on), whoever holds the URL. The answer carries the secret URL; it is shown only once. At most 15 webhooks per channel.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesChannel ID.

Request body (application/json, required): CreateRequest

FieldTypeDescription
allow_attachmentsboolean
allow_embedsboolean
allow_everyoneboolean
allow_identity_overrideboolean
allow_user_mentionsboolean
name (required)string

Responses

StatusMeaningBody
201Created.CreatedWebhook
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the channel does not exist or is hidden from the caller.ErrorResponse
409CONFLICT: the channel has the maximum number of webhooks.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
CreatedWebhook
FieldTypeDescription
allow_attachments (required)booleanAllowAttachments lets a post carry files (default on).
allow_embeds (required)booleanAllowEmbeds lets a post carry embeds (default on).
allow_everyone (required)booleanAllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions.
allow_identity_override (required)booleanAllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used.
allow_user_mentions (required)booleanAllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users).
avatar_urlstringAvatarURL is the API URL of the avatar; omitted when none is set.
channel_id (required)string (uuid)
created_at (required)string (date-time)
created_by (required)string | nullCreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing.
id (required)string (uuid)
name (required)string
token (required)stringToken is the secret part of the URL. It is stored hashed and cannot be shown again; regenerate the token to get a new URL.
updated_at (required)string (date-time)
url (required)stringURL is the full execute URL, token included.

Delete an outgoing webhook

DELETE /api/admin/outgoing-webhooks/{id}

Events still waiting to be delivered to it are dropped.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesOutgoing webhook ID.

Responses

StatusMeaningBody
204Deleted.
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such outgoing webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Change an outgoing webhook

PATCH /api/admin/outgoing-webhooks/{id}

Rename it, change its URL or events, switch it on or off. Switching it on clears an automatic switch-off. Records who set the URL and when (url_set_by, url_set_at).

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesOutgoing webhook ID.

Request body (application/json, required): UpdateOutgoingRequest

FieldTypeDescription
enabledboolean
eventsstring[]
namestring
urlstring

Responses

StatusMeaningBody
200Updated.Outgoing
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such outgoing webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Outgoing
FieldTypeDescription
channel_id (required)string (uuid)ChannelID is the channel the webhook belongs to; it receives that channel's events only.
consecutive_failures (required)integer
created_at (required)string (date-time)
created_by (required)string | nullCreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing.
events (required)string[]Events are the subscribed event types (see doc/webhooks.md).
id (required)string (uuid)
last_attempt_at (required)string | null
last_error (required)string | nullLastError is a short code for the latest failure ("timeout", "blocked_address", "http_500", ...); null after a success.
last_status (required)integer | nullLastStatus is the HTTP status of the latest attempt (null: none yet, or no response).
last_success_at (required)string | null
name (required)string
status (required)stringStatus is "active", "disabled" (switched off by an administrator) or "auto_disabled" (switched off after repeated failures).
url (required)string
url_set_at (required)string (date-time)
url_set_by (required)string | nullURLSetBy and URLSetAt record who last set the URL and when, so stale webhooks are easy to spot. The URL receives the channel's events until an administrator changes or deletes the webhook.

Recent deliveries of an outgoing webhook

GET /api/admin/outgoing-webhooks/{id}/deliveries

The last 50 attempts, newest first. Only status codes and short error codes are kept, never the receiver's response.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesOutgoing webhook ID.

Responses

StatusMeaningBody
200Attempts.Delivery[]
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this.ErrorResponse
404NOT_FOUND: no such outgoing webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Rotate an outgoing webhook's secret

POST /api/admin/outgoing-webhooks/{id}/secret

The old secret stops signing at once. The answer carries the new secret, shown only once. Nothing else changes.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesOutgoing webhook ID.

Responses

StatusMeaningBody
200New secret.CreatedOutgoing
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such outgoing webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
CreatedOutgoing
FieldTypeDescription
channel_id (required)string (uuid)ChannelID is the channel the webhook belongs to; it receives that channel's events only.
consecutive_failures (required)integer
created_at (required)string (date-time)
created_by (required)string | nullCreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing.
events (required)string[]Events are the subscribed event types (see doc/webhooks.md).
id (required)string (uuid)
last_attempt_at (required)string | null
last_error (required)string | nullLastError is a short code for the latest failure ("timeout", "blocked_address", "http_500", ...); null after a success.
last_status (required)integer | nullLastStatus is the HTTP status of the latest attempt (null: none yet, or no response).
last_success_at (required)string | null
name (required)string
secret (required)stringSecret signs every delivery (see X-Mnema-Signature in doc/webhooks.md).
status (required)stringStatus is "active", "disabled" (switched off by an administrator) or "auto_disabled" (switched off after repeated failures).
url (required)string
url_set_at (required)string (date-time)
url_set_by (required)string | nullURLSetBy and URLSetAt record who last set the URL and when, so stale webhooks are easy to spot. The URL receives the channel's events until an administrator changes or deletes the webhook.

Send a test event

POST /api/admin/outgoing-webhooks/{id}/test

Delivers a PING event once, right now, and answers with the attempt. It does not retry and does not count towards the automatic switch-off. Works while the webhook is switched off.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesOutgoing webhook ID.

Responses

StatusMeaningBody
200The attempt (success or the failure code).Delivery
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such outgoing webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Delivery
FieldTypeDescription
attempt (required)integer
created_at (required)string (date-time)
duration_ms (required)integer
error (required)string | nullError is a short code, never the response or the raw network error.
event_id (required)string (uuid)
event_type (required)string
id (required)string (uuid)
status_code (required)integer | null
success (required)boolean

Delete a webhook

DELETE /api/admin/webhooks/{id}

Its URL stops working at once. Messages it posted stay.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesWebhook ID.

Responses

StatusMeaningBody
204Deleted.
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Change a webhook

PATCH /api/admin/webhooks/{id}

Owner or Administrator only. Rename it and change its allow_* settings; omitted fields stay. Earlier messages keep the name they were posted under.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesWebhook ID.

Request body (application/json, required): UpdateRequest

FieldTypeDescription
allow_attachmentsboolean
allow_embedsboolean
allow_everyoneboolean
allow_identity_overrideboolean
allow_user_mentionsboolean
namestring

Responses

StatusMeaningBody
200Updated.Webhook
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Webhook
FieldTypeDescription
allow_attachments (required)booleanAllowAttachments lets a post carry files (default on).
allow_embeds (required)booleanAllowEmbeds lets a post carry embeds (default on).
allow_everyone (required)booleanAllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions.
allow_identity_override (required)booleanAllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used.
allow_user_mentions (required)booleanAllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users).
avatar_urlstringAvatarURL is the API URL of the avatar; omitted when none is set.
channel_id (required)string (uuid)
created_at (required)string (date-time)
created_by (required)string | nullCreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing.
id (required)string (uuid)
name (required)string
updated_at (required)string (date-time)

Set a webhook's avatar

POST /api/admin/webhooks/{id}/avatar

multipart/form-data with an image in field 'avatar' (max 5 MB). Replaces the previous one.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesWebhook ID.

Request body (multipart/form-data, required): object

FieldTypeDescription
avatar (required)string (binary)Image file, at most 5 MB.

Responses

StatusMeaningBody
200Updated.Webhook
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such webhook.ErrorResponse
413PAYLOAD_TOO_LARGE: file exceeds the limit.ErrorResponse
415UNSUPPORTED_MEDIA_TYPE: the file type is not allowed.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: file storage is not available.ErrorResponse
Webhook
FieldTypeDescription
allow_attachments (required)booleanAllowAttachments lets a post carry files (default on).
allow_embeds (required)booleanAllowEmbeds lets a post carry embeds (default on).
allow_everyone (required)booleanAllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions.
allow_identity_override (required)booleanAllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used.
allow_user_mentions (required)booleanAllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users).
avatar_urlstringAvatarURL is the API URL of the avatar; omitted when none is set.
channel_id (required)string (uuid)
created_at (required)string (date-time)
created_by (required)string | nullCreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing.
id (required)string (uuid)
name (required)string
updated_at (required)string (date-time)

Regenerate a webhook's token

POST /api/admin/webhooks/{id}/token

The old URL stops working at once. The answer carries the new secret URL; it is shown only once. Nothing else about the webhook changes.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesWebhook ID.

Responses

StatusMeaningBody
200New token and URL.CreatedWebhook
400Invalid input (INVALID_INPUT).ErrorResponse
401No valid session (UNAUTHORIZED).ErrorResponse
403FORBIDDEN: only the Owner and members with the Administrator permission may do this, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: no such webhook.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
CreatedWebhook
FieldTypeDescription
allow_attachments (required)booleanAllowAttachments lets a post carry files (default on).
allow_embeds (required)booleanAllowEmbeds lets a post carry embeds (default on).
allow_everyone (required)booleanAllowEveryone lets @all and @here notify people (default off). It also takes "everyone" in the sender's allowed_mentions.
allow_identity_override (required)booleanAllowIdentityOverride lets a post set its own username (default on). Avatars from other hosts are never used.
allow_user_mentions (required)booleanAllowUserMentions lets @username notify members (default on, as with allowed_mentions.parse = users).
avatar_urlstringAvatarURL is the API URL of the avatar; omitted when none is set.
channel_id (required)string (uuid)
created_at (required)string (date-time)
created_by (required)string | nullCreatedBy is the administrator who created it, kept for the record (null once that account is gone). It grants nothing.
id (required)string (uuid)
name (required)string
token (required)stringToken is the secret part of the URL. It is stored hashed and cannot be shown again; regenerate the token to get a new URL.
updated_at (required)string (date-time)
url (required)stringURL is the full execute URL, token included.

Execute a webhook

POST /api/webhooks/{id}/{token}

Posts a message into the webhook's channel as the webhook (the widely used execute format). Authenticated by the secret in the URL only: no cookie or CSRF origin is needed, and cookies are ignored. Send JSON, or multipart/form-data with the JSON in the payload_json part and up to 10 files in further parts (same size limit and type checks as member uploads). Errors are JSON with a message and a code ({"message","code"}); 429 carries retry_after. Limits: about 5 requests per 2 seconds per webhook and 30 per minute per channel. See doc/webhooks.md for what is supported and ignored.

Authentication: none

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesWebhook ID.
tokenpathstringyesWebhook token.
waitquerybooleannoAnswer 200 with the created message instead of 204.
thread_idquerystring (uuid)noID of a root message of the channel: the post becomes a reply in its thread.

Request body (application/json, required): ExecutePayload

FieldTypeDescription
allowed_mentions (required)AllowedMentionsAllowedMentions limits who is notified. Default: members mentioned by @username are, @all and @here are not.
avatar_url (required)stringAvatarURL is accepted and ignored: Mnema Talk never loads pictures from other hosts. Set the avatar on the webhook instead.
content (required)stringContent is the message text (Markdown), at most 4000 characters.
embeds (required)Embed[]Embeds are rich cards (at most 10).
username (required)stringUsername overrides the webhook's name for this message.

Responses

StatusMeaningBody
200The created message (wait=true).Message
204Posted.
400Invalid payload (50035) or empty message (50006).Error
401Invalid Webhook Token (50027).Error
404Unknown Webhook (10015) or unknown thread (10003).Error
413Request entity too large (40005).Error
429Rate limited; see retry_after and Retry-After.RateLimitError
500Server failure.Error
Message
FieldTypeDescription
attachments (required)MediaAttachment[]
avatar_urlstring
channel_id (required)string (uuid)
componentsActionRow[]Components are the buttons and select menus of a bot's message, in action rows (doc/bots.md, Message components). Only bots set them.
content (required)string
created_at (required)string (date-time)
direct_mentionsstring (uuid)[]DirectMentions are the users of Mentions this message addresses by name or through a role, not only by @all or @here: those a mute lets through. A name the sender's mention policy left as plain text is not in it. The server always sends it; it is optional so that a client can tell an older server (no field: read the text) from an empty list.
display_name (required)string
embedsEmbed[]Embeds are the rich cards of a webhook message (a subset).
expires_atstring (date-time)ExpiresAt is when the server deletes the message: the end of the lifetime its sender chose (doc/timed-messages.md). Absent on a message without one. Clients hide the message at that moment on their own clock.
forwardForwardRefForward is set when the message forwards another one. It says so and nothing more: no id and no text of the original travels with the message, because readers differ in what they may see. Each reader gets the original (with its ids) from GET /api/messages/{id}/forward.
id (required)string (uuid)
is_botbooleanIsBot is true for messages posted by a webhook. Their author is a hidden bot account; DisplayName is the webhook's name or the username the sender gave for this message.
is_edited (required)boolean
is_lockedbooleanIsLocked marks a forum post as locked: only moderators can post replies.
is_pinned (required)boolean
is_resolvedbooleanIsResolved marks a forum post as solved or answered.
is_webhookbooleanIsWebhook narrows IsBot: the author is an incoming webhook (shown with a Webhook label), not a bot account (shown with a BOT label).
last_activity_atstring (date-time)LastActivityAt is the timestamp of the latest reply in the thread, or the post's creation time.
mention_rolesstring (uuid)[]MentionRoles are the roles this message mentions (@Role); the client draws them as role pills. A role that was deleted since drops out. The server always sends it; it is optional for clients that build messages themselves.
mentions (required)string (uuid)[]Mentions are the users this message mentions (@username, @all, @here).
noncestring (uuid)Nonce is the id the author's client put on this send. Only the message_create event and the reply to that send carry it, so the client can replace its pending copy; history never does.
number (required)integerNumber is the message's short, stable link number (/m/4821).
parent_idstring (uuid)
pinned_atstring (date-time)PinnedAt and PinnedBy say when and by whom a pinned message was pinned; both are absent on an unpinned message (PinnedBy also when the member is gone).
pinned_byUserRef
pollPollPoll is set when the message is a poll; its content is the question.
reactions (required)ReactionSummary[]
reply_count (required)integer
reply_toReplyPreview
reply_to_idstring (uuid)
tagsForumTag[]Tags are the forum tags attached to a forum post (up to 5 tags).
titlestringTitle is the required title of a root post in a forum channel (max 100 characters).
updated_at (required)string (date-time)
user_id (required)string (uuid)
username (required)string

Something wrong on this page? Tell us.