JetBrains Space Help

Use Webhooks

Webhooks let your application receive notifications about events in Space. When an event is triggered, Space will send a POST request to the specified application endpoint. The request contains JSON payload with event details.

In Space, webhooks are an integral part of applications: Each application can have its own set of configured webhooks, and it's not possible to create a webhook separately from an application.

Create a webhook

  1. In Extensions | Applications, open the required application.

  2. Open the Webhooks tab and click New webhook.

  3. Specify the webhook Name and click Create.

Specify a webhook endpoint

The endpoint is a URL where Space will send POST requests when events occur. By default, Space will use the endpoint specified for the application.

  1. On the Webhooks tab, open the required webhook.

  2. If you want to use the endpoint different from the application's endpoint, click the Edit Edit button next to Endpoint. Then turn off Use application settings and sepcify new Endpoint URL and other options.

  3. If you want to use a verification method different from the application's verification method, click the EditEdit button next to Authentication. Then turn off Use application settings and specify a new verification method.

  4. Typically, after Space sends a POST request, the application must respond with the 200 OK HTTP status. By default, Space treats all 2xx codes as successful. If you want Space to accept other codes as successful, add these codes to the Successful HTTP response status codes list.

    In case, Space receives some other code or doesn't receive a response at all, it will try to resend the request up to three times. To disable this behavior, clear Retry on failure in the Endpoint settings.

  5. After you configure the endpoint, you can test the configuration by clicking the Test endpoint button. In this case, Space will send a request with the PingWebhookEvent payload. Note that your application must accept this payload type. Learn more

Subscribe to events

A webhook is allowed to have any number of subscriptions to events. A webhook subscription to an event looks almost the same as a user subscription.

  1. Click the AddAdd button next to Subscriptions.

  2. Specify subscription's Name and other settings:

    • Source: a Space module from which you want to receive notifications, for example, Teams, Issues, Meetings, and so on.

    • Events: an event that triggers sending a POST request to the application. The list of available events depends on the selected Source.

    • Additional filters: you can narrow the subscription scope by specifying additional event filters. The list of available filters depends on the selected Source. For example, this could be Filter by team, Filter by project, Filter by location, and so on.

    Webhook event subscription

Send webhook event data as URL parameters

By default, Space sends event data to the webhook endpoint in an HTTP request payload. Also, Space can send the data as endpoint URL parameters. To make it work, you should use macros when specifying the webhook endpoint URL. Macros are placeholders that will be substituted with real event values when the event occurs. For example, https://my.endpoint.url/api?id={{member.id}} will transform into a real user ID, like https://my.endpoint.url/api?id=1234.

  1. Open the webhook settings.

  2. Open the Endpoint settings by clicking the Edit Edit button.

  3. Clear the Use application settings checkbox.

  4. Specify the endpoint URL with required macros.

    The macros available in the current context correspond to the properties of the event type. For example, if your webhook is subscribed to the Blog post published event, Space will send a payload of the BlogWebhookEvent type. This means that you can use BlogWebhookEvent type properties as URL macros. For instance, to get a title of a blog post: https://my.endpoint.url/api?id={{title}}.

    The Edit Endpoint window shows the list of macros availalble in the current context.

    URL macros

Customize requests

Space lets you customize headers of requests that will be sent to the application. Typically, this makes sense in case your application uses a non-standard authentication/authorization flow.

  1. On the Webhooks tab, open the required webhook.

  2. Click the AddAdd button next to Custom Headers.

  3. Specify a Name of the header and provide its Value.

  4. Click Save.

View webhook request history

  1. On the Webhooks tab, open the required webhook.

  2. Open the Recent Deliveries tab.

Process webhook notifications in an application

When an event is triggered, a webhook will send a WebhookRequestPayload to the application's endpoint. To help you process the event payload, Space SDK provides a number of classes. After processing the payload, the application must respond with the 200 OK HTTP status.

Here you can find an example of an application that shows how to process webhook payload.

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 } }

Process 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. You can find the full list of event classes in the API reference.

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.

Test 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: 29 September 2022