In January 2020, webhooks were introduced as a feature on the DRACOON cloud. With webhooks, notifications on several types of events can be sent to an external service to realize integrations without the need to regularly poll the DRACOON API.

Please keep in mind that we do not provide a configuration user interface to evaluate our implementation at the moment. Instead, please use the Swagger UI, available at https://dracoon.team/api (here, dracoon.team is just an example of a DRACOON environment, which you can replace with your own environment).

Overview

To comply with our high standards of security and our philosophy to empower a customer's central management but at the same time limit access for administrative users to corporate documents, we decided that webhooks can be configured by the Configuration Manager only. This ensures that a company controls which external services are notified/integrated with DRACOON.

However, since a Configuration Manager must not decide by themselves that a service should receive sensitive information about e.g. transferred files, all webhooks triggered by file-related events need to be authorized on each data room by the respective data room administrator before those events may be received.

HTTP POST requests

All registered webhooks send an HTTP POST request to the registered URL for the subscribed event type. Those HTTP POST messages have a JSON body that is transmitted to the receiving service and contains some meta information about the triggered event and an event-type-specific payload with detailed information about the affected DRACOON object (e.g. a file or a user).

The JSON body has the following structure:

{
  "authParentId": long, data room in which the event occured, might be NULL
  "eventType": long, id of even type
  "customerId": long, id of customer
  "sourceHost": string, source hostname of DRACOON, e.g. "dracoon.team"
  "timeStamp": long, timestamp of event
  "webhookId": long, id of the web hook
  "webhookUrl": string, request URL of this web hook,
  "payload": JSON document, event-type-specific payload (see below)
}

The payload depends on the event type (see below).

Security of the HTTP POST requests

To prevent your receiving service from having injected false messages, during the creation of a webhook, you should provide a "secret", which is a random string only known by your service and provided for DRACOON. All POST requests sent by DRACOON to the URL that is configured with the webhook will carry a custom HTTP header:

X-DRACOON-Signature: HmacSHA256=$HMAC

In this header, "$HMAC" is replaced with an RFC2104-compliant HmacSHA256 that is calculated of the complete request body:

HMAC = HmacSHA256(secret, body)

Event types

We support several event types that may trigger webhooks. Following a list of all currently supported actions and the triggered events together with their respective payload model that is transferred in the HTTP request.

A list of all available event types with their IDs may be retrieved at https://dracoon.team/api/swagger-ui.html#/settings/getListOfEventTypesForConfigManager.

The following event types are triggered in the context of a data room:

The following event types do not require the context of a data room:

For provider environments, some additional webhooks out of customer contexts are available:

Payload models

All webhooks are sent as HTTP POST requests with a JSON payload.

Node payload

The attributes correspond to the respective attributes of the Node model:
https://dracoon.team/api/swagger-ui.html#/nodes/getFsNode

"payload": {

 "baseUrl": string
  "id": long
  "type": string
  "name": string
  "parentId": long
  "parentPath": string
  "createdAt": Date
  "createdById": long
  "updatedAt": Date
  "updatedById": long
  "expireAt": Date
  "hash": string
  "fileType": string
  "mediaType": string
  "size": long
  "classification": int
  "notes": string
  "inheritPermissions": boolean
  "isEncrypted": boolean
  "cntDeletedVersions": long
  "cntComments": long
  "cntDownloadShares": long
  "cntUploadShares": long
  "recycleBinRetentionPeriod": long
  "hasActivitiesLog": boolean
  "quota": long
  "branchVersion": long
  "mediaToken": string
  "cntRooms": long
  "cntFolders": long
  "cntFiles": long
}

DownloadShare payload

The attributes correspond to the respective attributes of the DownloadShare model:
https://dracoon.team/api/swagger-ui.html#/shares/getDownloadShare

"payload": {
 "baseUrl": string
  "id": long
  "name": string
  "nodeId": long
  "accessKey": string
  "notifyCreator": boolean
  "cntDownloads": integer
  "createdAt": Date
  "createdById": long
  "updatedAt": Date
  "updatedById": long
  "notes": string
  "internalNotes": string
  "showCreatorName": boolean
  "showCreatorUsername": boolean
  "isProtected": boolean
  "expireAt": Date
  "maxDownloads": integer
  "nodePath": string
  "dataUrl": string
  "isEncrypted": boolean
}

PublicDownloadShare payload

The attributes correspond to the respective attributes of the public DownloadShare model:
https://dracoon.team/api/swagger-ui.html#/public/getPublicDownloadShare

"payload": {
 "baseUrl": string
  "isProtected": boolean
  "fileName": string
  "size": long
  "limitReached": boolean
  "creatorName": string
  "createdAt": Date
  "hasDownloadLimit": boolean
  "mediaType": string
  "name": string
  "creatorUsername": string
  "expireAt": Date
  "notes": string
  "isEncrypted": boolean
}

UploadShare payload

The attributes correspond to the respective attributes of the UploadShare model:
https://dracoon.team/api/swagger-ui.html#/shares/getUploadShare

"payload": {
 "baseUrl": string
  "id": long
  "name": string
  "targetId": long
  "isProtected": boolean
  "accessKey": string
  "notifyCreator": boolean
  "createdAt": Date
  "createdById": long
  "updatedAt": Date
  "updatedById": long
  "expireAt": Date
  "targetPath": string
  "isEncrypted": boolean
  "notes": string
  "internalNotes": string
  "filesExpiryPeriod": integer
  "cntFiles": integer
  "cntUploads": integer
  "showUploadedFiles": boolean
  "dataUrl": string
  "maxSlots": integer
  "maxSize": long
  "targetType": string
  "showCreatorName": boolean
  "showCreatorUsername": boolean
}

PublicUploadShare payload

The attributes correspond to the respective attributes of the public UploadShare model:
https://dracoon.team/api/swagger-ui.html#/public/getPublicUploadShare

"payload": {
 "baseUrl": string
  "isProtected": boolean
  "createdAt": Date
  "name": string
  "isEncrypted": boolean
  "expireAt": Date
  "notes": string
  "showUploadedFiles": boolean
  "remainingSize": long
  "remainingSlots": integer
  "creatorName": string
  "creatorUsername": string
}

UserData payload

The attributes correspond to the respective attributes of the User model:
https://dracoon.team/api/swagger-ui.html#/users/getUser

"payload": {
 "baseUrl": string
  "id": long
  "userName": string
  "firstName": string
  "lastName": string
  "isLocked": boolean
  "avatarUuid": string
  "email": string
  "phone": string
  "title": string
  "expireAt": Date
  "hasManageableRooms": boolean
  "isEncryptionEnabled": boolean
  "lastLoginSuccessAt": Date
  "homeRoomId": long
}

Customer payload

The attributes correspond to the respective attributes of the Customer model:
https://dracoon.team/api/swagger-ui.html#/provisioning/getCustomer

"payload": {
 "baseUrl": string
  "id": long
  "companyName": string
  "customerContractType": string
  "quotaMax": long
  "quotaUsed": long
  "userMax": integer
  "userUsed": integer
  "createdAt": Date
  "isLocked": boolean
  "trialDaysLeft": integer
  "updatedAt": Date
  "lastLoginAt": Date
  "providerCustomerId": string
}

Webhook payload

The attributes correspond to the respective attributes of the public Webhook model:
https://dracoon.team/api/swagger-ui.html#/settings/getWebhook

"payload": {
 "baseUrl": string
  "id": long
  "name": string
  "url": string
  "secret": string
  "isEnabled": boolean
  "endOfLife": Date
  "eventTypeNames": list of strings
  "createdAt": Date
  "createdById": long
  "updatedAt": Date
  "updatedById": long
  "failStatus": integer
  "triggerExampleEvent": boolean
}

Creating webhooks

Config Managers may create webhooks with a set of attributes that are documented in our Swagger documentation: https://dracoon.team/api/swagger-ui.html#/settings/createWebhook.

The DRACOON API offers to trigger a test event upon the creation or update of a new webhook. In those cases, a POST request is sent that contains an empty payload (NULL) and an empty authParentId (NULL).

Permitting webhooks

Webhooks at globals scopes do not require additional tasks to be fully functional. However, all webhooks that relate to DRACOON nodes (files/folders/rooms) must be permitted in each data room where they should be able to trigger events. This is done by the data room administrator with the following APIs:

https://dracoon.team/api/swagger-ui.html#/nodes/getListOfWebhooksForRoom lists all currently active webhooks for that data room (filter "isAssigned:eq:true") and may also list all webhooks that are available to be permitted on this data room (filter "isAssigned:eq:false").

Assignment and unassignment of webhooks on this data room are done with https://dracoon.team/api/swagger-ui.html#/nodes/handleRoomWebhookAssignments. 

After this final step, all registered events in this data room are notified to the external service as HTTP POST requests.

Expiration of webhooks

All webhooks have a default lifetime of one year after creation. However, the lifetime may be reset before it expires to keep it alive.

Automated disabling of webhooks

If the webhook target responds three times in a row with an error code (i.e. not HTTP 2xx), the webhook is disabled. This counter is reset if a request is responded to with a confirmation (HTTP 2xxx). The last received error code can be retrieved using the API https://dracoon.team/api/swagger-ui.html#/settings/getWebhooks.

Responding to webhooks

Our webhook service expects a response in due time with a 2xx response. If the web server receiving the webhooks does not respond within 10 seconds, the request will be retried multiple times. If none of the retries succeed, the webhooks will be disabled (see above).