liz/PluralKit
liz/PluralKit
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(webhooks): docs

Browse Source
This commit is contained in:
spiral 2021-11-22 14:20:43 -05:00
parent 40dbf7dad6
commit 51c900a378
No known key found for this signature in database
GPG Key ID: A6059F0CA0E1BD31
2 changed files with 59 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
PluralKit.Core/Dispatch/DispatchModels.cs
View File

@ -54,9 +54,7 @@ namespace PluralKit.Core
o.Add("type", data.Event.ToString()); o.Add("type", data.Event.ToString());
o.Add("signing_token", data.SigningToken); o.Add("signing_token", data.SigningToken);
o.Add("system_id", data.SystemId); o.Add("system_id", data.SystemId);
if (data.EntityId != null)
o.Add("id", data.EntityId); o.Add("id", data.EntityId);
if (data.GuildId != null)
o.Add("guild_id", data.GuildId); o.Add("guild_id", data.GuildId);
o.Add("data", data.EventData); o.Add("data", data.EventData);

57
docs/content/api/dispatch.md Normal file
View File

@ -0,0 +1,57 @@
---
title: Dispatch Webhooks
permalink: /api/dispatch
---
# Dispatch Webhooks
todo: write text here
## Security
::: warning
On the internet, security is important! Don't skip this section.
:::
To get dispatch events from PluralKit, you must set up a *public* HTTP endpoint. As such, anyone who knows the URL to the endpoint - **not only PluralKit** - can send POST requests and "pretend" to be PluralKit.
For this reason, when you register a webhook URL, PluralKit generates a secret token, and then includes it with every event sent to you in the `signing_token` key. If you receive an event with an invalid `signing_token`, you **must** stop processing the request and **respond with a 401 status code**.
PluralKit will send invalid requests to your endpoint, with `PING` event type, once in a while to confirm that you are correctly validating requests.
## Dispatch Event Model
|key|type|description|
|---|---|---|
|type|string|[event type](#event-type-enum)|
|signing_token|string|the [signing token](#security) for your webhook URL|
|system_id|string|the system ID associated with this event|
|id|string?|the ID of the entity referenced by the event (can be a system/member/group/switch/Discord user ID)|
|guild_id|snowflake?*|the ID of the guild where this event occurred|
|data|object?|event data|
\* only sent for guild settings update events. in message create events, the guild id is sent in the `data` object
## Dispatch Events
|name|description|content of `data` object|notes|
|---|---|---|---|
|PING|PluralKit is checking if your webhook URL is working.|null|Reply with a 200 status code if the `signing_token` is correct, or a 401 status code if it is invalid.|
|UPDATE_SYSTEM|your system was updated|[system object](/api/models#system-model) only containing modififed keys|
|CREATE_MEMBER|a new member was created|[member object](/api/models#member-model) only containing `name` key|new member ID can be found in the top-level `id` key`|
|UPDATE_MEMBER|a member was updated|[member object](/api/models#member-model) only containing modified keys|member ID can be found in the top-level `id` key`|
|DELETE_MEMBER|a member was deleted|null|old member ID can be found in the top-level `id` key`|
|CREATE_GROUP|a new group was created|[group object](/api/models#group-model) only containing `name` key|new group ID can be found in the top-level `id` key`|
|UPDATE_GROUP|a group was updated|[group object](/api/models#group-model) only containing modified keys|group ID can be found in the top-level `id` key`|
|UPDATE_GROUP_MEMBERS|the member list of a group was updated|unknown|This event is currently non-functional|
|DELETE_GROUP|a group was deleted|null|old group ID can be found in the top-level `id` key`|
|LINK_ACCOUNT|a new Discord account was linked to your system|null|new account ID can be found in the top-level `id` key|
|UNLINK_ACCOUNT|a Discord account was unlinked from your system|null|old account ID can be found in the top-level `id` key|
|UPDATE_SYSTEM_GUILD|your system settings in a specific server were updated|[system guild settings](/api/models#system-guild-settings) with only modified keys|
|UPDATE_MEMBER_GUILD|the settings for a member in a specific server were updated|[member guild settings](/api/models#member-guild-settings) with only modified keys|
|CREATE_MESSAGE|a message was sent|[message object](/api/models#message-model)|
|CREATE_SWITCH|a new switch was logged|[switch object](/api/models#switch-model)|
|UPDATE_SWITCH|a switch was updated|[switch object](/api/models#switch-model) with only modified keys|
|UPDATE_SWITCH_MEMBERS|the member list of a switch was updated|list of member IDs|
|DELETE_SWITCH|a switch was deleted|null|old switch ID can be found in top-level `id` key|
|DELETE_ALL_SWITCHES|your system's switches were bulk deleted|null|