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.

Creating a webhook

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

  2. Open the Webhooks tab and click New webhook.

  3. Specify the webhook Name and click Create.

Specifying 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

Subscribing 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

Processing 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. Learn more

You can also take a look at the sample application that shows how to process webhook payload.

Sending 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={{}} 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

Customizing 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.

Viewing webhook request history

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

  2. Open the Recent Deliveries tab.

Last modified: 27 May 2022