4.0 KiB
| title | permalink |
|---|---|
| Dispatch | /api/dispatch |
Dispatch Webhooks
Dispatch webhooks are a way to get notified when you update your system information on PluralKit. It can be used for integrations where you want to perform some action when you run a bot command on Discord, but also don't want to (or can't) set up a Discord bot to listen to messages.
You will need a publicly-accessible webserver that can receive and process JSON-formatted POST requests.
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 |
| signing_token | string | the signing token 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) |
| data | object? | event data |
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 only containing modififed keys | |
| CREATE_MEMBER | a new member was created | member object only containing name key |
new member ID can be found in the top-level id key` |
| UPDATE_MEMBER | a member was updated | member object 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 only containing name key |
new group ID can be found in the top-level id key` |
| UPDATE_GROUP | a group was updated | group object 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 with only modified keys | |
| UPDATE_MEMBER_GUILD | the settings for a member in a specific server were updated | member guild settings with only modified keys | |
| CREATE_MESSAGE | a message was sent | message object | |
| CREATE_SWITCH | a new switch was logged | switch object | |
| UPDATE_SWITCH | a switch was updated | switch object 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 | |
| SUCCESSFUL_IMPORT | some information was successfully imported through the pk;import command to your system |
null |