JetBrains Space Help

WebhookRequestPayload Class

Relevant for

Applications that receive notifications about events in Space using webhooks.

Sent on

Each time a particular event occurs in Space. The payload is sent only if the application is subscribed to this event with a webhook.

Payload contents

For example, this payload is sent when a new user is added to the organization:

{ "className": "WebhookRequestPayload", "accessToken": "", "verificationToken": null, "serverUrl": "https://mycompany.jetbrains.space", "clientId": "a1b83dac-6e26-46cb-b3cb-7e264eab5e9e", "orgId": "o0Ghr0EewX8", // id issued to a webhook during registration "webhookId": "3EZUCW3RmsZY", "payload": { // event class name "className": "ProfileOrganizationEvent", // event-specific data "meta": { "principal": { "name": "admin", "details": { "className": "CUserPrincipalDetails", "user": { "id": "2ZJrHC3ouUQz" } } }, "timestamp": { "iso": "2021-06-15T14:51:35.545Z", "timestamp": 1623768695545 }, "method": "Created" }, "member": { "id": "4Zg1mS4aBsOm" }, "joinedOrganization": true, "leftOrganization": false } }

Application response

The application must respond with the 200 OK HTTP status.

Processing event payload

To help you process the event payload, Space SDK provides a number of classes: A separate class for each event type. All these classes implement the WebhookEvent interface. Properties of the event classes let you get particular data from the event payload.

For example, you can create a webhook for the Member joined organization event. In this case, each time a new user is added to the organization, Space will send an instance of the ProfileOrganizationEvent class to the application. You can use its properties to get data on the added user:

if (event is ProfileOrganizationEvent) { // get id of the created member from event val userId = event.member.id // use id to get username val username = userId.let { val profile = spaceClient.teamDirectory.profiles. getProfile(ProfileIdentifier.Id(userId)) println("ADDED USER: ${profile.username}") } }

You can get the detailed information about a particular event class when adding a subscription to the webhook.

Testing webhook connection

When adding a webhook, you can test the connection to the application using the Test endpoint button on the Endpoint page.

Test endpoint

This will send the payload of the PingWebhookEvent class. Make sure you handle this type of event in your application. For example, this is the PingWebhookEvent payload of a webhook with the MyFirstWebhook name:

{ "className": "WebhookRequestPayload", "accessToken": "", "verificationToken": null, "serverUrl": "https://mycompany.jetbrains.space", "clientId": "135d429f-4d7e-4aa1-9872-ea5ba0b6736e", "orgId": "o0Ghr0EewX8", "webhookId": "1HArWk184jyL", "payload": { "className": "PingWebhookEvent", "webhookName": "MyFirstWebhook" } }

Customizable payload

To reduce the payload size, Space sends only the minimum required data set. More specifically, it sends only top-level properties.

For example, a payload of the TeamMembershipEvent class has the membership: TD_Membership property. By default, Space will send only the membership.id in the payload.

{ "className": "WebhookRequestPayload", ... "payload": { "className": "TeamMembershipEvent", ... "membership": { "id": "30PnZX2QSoWo" }, ... } }

To get other membership properties, you must request them explicitly when configuring a webhook.

Example

In the following example, the application's webhook is subscribed to the TeamMembership created and TeamMembership updated events. When a user joins the 'Cool Team' team, the application sends a greeting message to the user:

fun main() { embeddedServer(Netty, port = 8080) { routing { post("/api/from-space") { val body = call.receiveText() val payload = readPayload(body) when (payload) { // get event payload from the webhook payload is WebhookRequestPayload -> payload.payload // here goes handling of other payloads else -> call.respond(HttpStatusCode.BadRequest, "Unsupported payload type") } when (event) { // TeamMembershipEvent occurs when a user is // moved to or removed from a team is TeamMembershipEvent -> { val userId = event.membership.member?.id if (userId != null) { when (event.membership.team.name) { "Cool Team" -> sendMessage(userId, coolTeamMessage()) // other teams } } call.respond(HttpStatusCode.OK, "") } // respond to 'Test endpoint' button in webhook settings is PingWebhookEvent -> { call.respond(HttpStatusCode.OK, "Pong") } else -> error("Unexpected event type") } } } }.start(wait = true) }
Last modified: 25 August 2021