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:
Action | Triggered Event | Payload Model (details below) |
---|---|---|
File uploaded / new version of file uploaded | file.created | Node payload |
Folder created | folder.created | Node payload |
Room created | room.created | Node payload |
File deleted | file.deleted | Node payload |
Folder deleted | folder.deleted | Node payload |
Room deleted | room.deleted | Node payload |
Share created | downloadshare.created | DownloadShare payload |
Share used to download file | downloadshare.used | PublicDownloadShare payload |
Share expired | downloadshare.deleted | DownloadShare payload |
Share deleted | downloadshare.deleted | DownloadShare payload |
File request created | uploadshare.created | UploadShare payload |
File request used to upload file | uploadshare.used file.created |
PublicUploadShare payload Node payload |
File request expired | uploadshare.deleted | UploadShare payload |
File request deleted | uploadshare.deleted | UploadShare payload |
The following event types do not require the context of a data room:
Action | Triggered Event | Payload Model (details below) |
---|---|---|
User created | user.created | UserData payload |
User auto-created by AD auto-import | user.created | UserData payload |
User auto-created by OIDC auto-import | user.created | UserData payload |
User locked | user.locked | UserData payload |
User deleted | user.deleted | UserData payload |
User expired | user.deleted | UserData payload |
Webhook is about to expire | webhook.expiring | Webhook payload |
For provider environments, some additional webhooks out of customer contexts are available:
Action | Triggered Event | Payload Model (details below) |
---|---|---|
Customer was created | customer.created | Customer payload |
Customer was deleted | customer.deleted | Customer payload |
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.
Kommentare
0 Kommentare
Zu diesem Beitrag können keine Kommentare hinterlassen werden.