Webhooks are meant to commit a request when some event happens.

Hooks are triggered by documents only.

Hook properties

    "_id": "57114ee832d2c668de756b5d",
    "collection": "_files",
    "condition": {
        "additionalProperties": true,
        "properties": {
            "name": {
                "enum": [
                "type": "string"
        "type": "object"
    "headers": {
        "Authorization": "Bearer <secret-value>",
        "Content-Type": "application/json"
    "method": "GET",
    "name": "files_hook",
    "triggers": [
    "url": "https://example.com/url-to-post-to",
    "timeout": {
        "read": 10,
        "connect": 1,
    "retry": {
        "strategy": "exponential"
Property Type Description
_id string unique identity of the hook
name string name of a hook
collection string collection which contains a documents called hook to trigger
condition object condition of a successful hook trigger
headers object http request headers
method string http method to commit a request
triggers array document event to trigger a hook
request_payload_wrapper string name of payload property
url string url to commit a http request
timeout object timeouts to connect and read
retry object retry settings


All documents from this collection will be used to be a hook trigger


This is a schema. If a document which triggered this hook matches this condition schema - this hook will commit an operation, otherwise it won't.


Hook will contain these headers in a request:

Header Description
X-Hook-ID _id of a hook
X-Hook-Trigger event of a document which caused hook to trigger
X-Hook-Operation-ID operation is _id of a hook. Can be found in a _hooks_history

If method is PUT, PATCH or POST:

Header Value Description
Content-Type application/json Body will contain document's JSON
Content-Length Length of document's JSON

In some cases you may need a webhook to pass a custom header with a request it commits.


A method is being used to commit a HTTP Request. Valud values are GET, POST, DELETE or PUT.

Method Body Content-Type
PUT * application/json
PATCH * application/json
POST * application/json

In some cases you may need a webhook to PUT a processed document to your cache or database.


When a document event matches created, updated, deleted the webhook triggers.


By default a payload of a webhook is wrapped to payload property.

Sometimes you may need it to be a different root property.



Timeout to connect


Timeout to read read response



Strategy can be exponential or constant

exponential strategy requeues hook trigger for 2, 4, 8, 16, 32 ... seconds

constant strategy requeues hook trigger for in 2 seconds


hook url to request

Hook retry policy

If url response contains the header Retry-After the hook will tolerate it.

If response contains redirects - the hook will also follow redirects. Up to 5 redirects are allowed.

Hook results

The item of a history will have a status according received HTTP response Status Code.

Status Status Codes
Success 200, 201, 202, 204
Error 500, 501, 502, 503, 504, 505, 400, 401, 403, 404, 405, 410
Redirect 301, 302, 305, 307