Webhooks

Webhooks

---

(note: This describes a feature that is still a work in progress. Details may change in the final implementation.)

The Webhooks feature allows the sync gateway to perform an asynchronous HTTP POST to a specified location when a document is updated, sending the document body as the payload. One or more webhook instances may be defined in the sync gateway configuration file. Each webhook entry has the following parameters:

• url: The URL used for the HTTP POST.
• timeout (optional): Time to wait (in seconds) for a response to the POST before cancelling. If no value is provided, the default value of 60 seconds is used.
• filter (optional): Javascript function to filter which documents should be posted. The function accepts the document body as input, and expects a boolean return value. The HTTP POST will be cancelled if the filter function returns a value of false. If no filter is defined, all updates are posted.

##Configuration Webhooks are defined in a new 'event_handlers' property in the database configuration section of the JSON configuration. Here is a sample entry for a simple webhook:

"event_handlers": {
    "document_changed": [
     {"handler": "webhook",
      "url": "http://someurl.com"},
     }
    ]
}

Here document_changed describes the event type associated with the webhook event handler. This is the only currently supported event.

Here is a sample configuration which defines a second webhook that uses the optional timeout and filter parameters:

"event_handlers": {
      "document_changed": [
        {"handler": "webhook",
         "url": "http://someurl.com"},
        {"handler": "webhook",
         "url": "http://someurl.com/some_type",
         "timeout": 30,
         "filter": `function(doc) {
              if (doc.type == "some_type") {
                return true;
              }
              return false;
            }`
        }
      ]
    }

##Performance Tuning

The webhook implementation is intended to minimize the performance impact on Sync Gateway's regular processing. When a document has been successfully updated by Sync Gateway, a 'document_changed' event is added to an asynchronous event processing queue. New processes are then spawned to perform the HTTP POST operations on each event.

It's important to manage the number of processes that are spawned for webhook handling - otherwise slow response time from the HTTP POSTs could result in event processing using up the CPU available on the sync gateway node. This is managed with two optional config settings, which can be tuned based on your use case and server capabilities:

• max_processes: The maximum number of events that will be processed concurrently. Defaults to 500.
• wait_for_process: The maximum wait time (in ms) before cancelling webhook processing for the update. Defaults to 5.

No more than max_processes concurrent processes will be spawned for webhook handling. The event queue is capped at a size of 3 x max_processes (to handle temporary event inflow spikes). When the event queue is full, events will be discarded after waiting for wait_for_process ms.

Some potential use cases:

• To avoid any blocking of the standard sync gateway processing, set wait_for_process=0. Any incoming events when the queue is full will be immediately discarded.
• To ensure all webhooks are sent, set wait_for_process to a sufficiently high value (at least greater than the webhook timeout value)

Here is a sample config using the tuning parameters:

"event_handlers": {
      "max_processes" : 1000,
      "wait_for_process" : "2",
      "document_changed": [
        {"handler": "webhook",
         "url": "http://someurl.com"}
      ]
    }

Note that wait_for_process is defined as a string value in the config - this is to support both empty and zero values.

##Additional details

• When an event is skipped, a warning message is logged in the sync gateway's log.
• Additional event logging can be enabled using the "Events" or "Events+" log channels