Using webhooks in DocSpace

First of all, you need to set up an endpoint for webhooks within your external service. This endpoint will be used to listen for DocSpace webhooks and receive event notifications.

Once you create and configure your endpoint, you can create webhooks in DocSpace. To create a new webhook,

1. Use the menu in the lower left corner and select the Settings option.
2. In the DocSpace settings, open the Developer Tools section on the left.
3. Go to the Webhooks section.
4. Click the Create webhook button.
5. Set the necessary parameters:
   • Webhook name – an identifier name for convenient work with the webhook on the portal.
   • Payload URL – an address of the endpoint where the webhook should be sent.
   • Secret key – set a webhook secret which allows you to verify requests sent to the payload URL. Enter your own key or click Generate. Please note: you cannot retrieve your secret key again once it has been saved. If you've lost or forgotten this secret key, you can reset it, but all integrations using this secret will need to be updated.
   • SSL verification – by default, this option is enabled to verify SSL certificates when delivering payloads. It’s not recommended to disable this parameter.
6. Click the Create button.

The created webhook will be assigned to all DocSpace events. You will receive automatic notifications on DocSpace events within your external service.

You can disable or re-enable the created webhook using the switcher next to it. Use the icon on the right to change the webhook settings specified during its creation, view the webhook history, or delete the webhook.

When viewing history, you can filter webhooks by delivery date or status (Not sent, 2XX, 3XX, 4XX, 5XX). Click the filter button, choose the necessary parameters and click Apply.

You can select one or more webhooks in the list and use the Retry option which appears on the top to redeliver the selected webhooks. Or click the icon next to the certain webhook and select the Retry option in the context menu.

Click the icon next to the certain webhook and select the Webhook details option in the context menu.

The following details are available:

• Status – a response status.
• Event ID – an ID of the event.
• Event time – a date when the event occurred.
• Delivery time – a date when the webhook was sent to the endpoint.

In the Request/Response sections, you can also view the POST request header, POST request body, POST response header, and POST response body. Use the icon to copy the request or response header/body to the clipboard.

Use the icon next to the Webhook details caption to redeliver the webhook.

The following two services are used for work:

1. ASC.Web.Studio provides methods for sending webhooks, launches WorkerService.

   WorkerService – subscribes for receiving messages from a broker (for example, kafka), which stores information about new webhooks waiting to be sent. Messages received from the broker are placed in a queue, after that the queue is constantly queried and asynchronously contacts ASC.Webhoks.Service to send webhooks.

2. ASC.Webhooks.Core provides methods for publishing webhooks to the database and the message broker, as well as methods for working with the database.

Currently, webhooks are triggered by any requests to the API, such as post, update, and delete.

For more details on DocSpace API, please refer to api.onlyoffice.com.