Articles with the tag:
Close
Changelog
Close
Try in the cloud

Using webhooks in DocSpace

Introduction

Webhooks allow notifying a pre-configured recipient about events on the portal using the http/https callbacks. A user can configure webhooks so that events on the portal trigger actions on external services. This approach can be useful for synchronizing and tracking certain events.

Use webhooks to perform custom actions on the side of any application or website you are using based on various events in ONLYOFFICE DocSpace.

You can create and manage all your webhooks, configure them, and browse history of every webhook to audit their performance.

Creating a new webhook

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 Options icon 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.

Using webhooks in DocSpace Using webhooks in DocSpace

Managing webhooks

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

Using webhooks in DocSpace Using webhooks in DocSpace

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

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

Using webhooks in DocSpace Using webhooks in DocSpace

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

Using webhooks in DocSpace Using webhooks in DocSpace

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 Copy icon icon to copy the request or response header/body to the clipboard.

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

Technical details

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.

Try now for free Try and make your decision No need to install anything
to see all the features in action
You Might Also Like This:
Close