Loading...
Area: Episerver Add-ons
Applies to versions: 4.3 and higher

Implementing a WebHook actor

Recommendations [hide]

Note: Episerver Forms is only supported by MVC-based websites and HTML5-compliant browsers.

WebHook is a simple event notification via HTTP POST; when a WebHook event is triggered, a HTTP POST request is sent to a URL. 

Episerver has built-in WebHooks, inspired by GitHub webhook specs. As a publisher of the event, WebHooks rings the bell of remote URL, push enough information and send the payload away.

Instead of customizing the URL in edit view (as a site administrator), customize the URL as a developer by implementing a receiver to handle the incoming HttpRequest to process the data; take the data structure directly in HttpHandler, and consume it. It is developer-friendly and less error-prone than managing two places (URL in the edit view and a handler in the receiver code).

The default WebHookActor supports a list of several WebHook URLs to send out the payload.

Configure data format

Use the serializingObjectUsingNameValueFormat key (in the Forms.config file) to set up the kind of data format used before sending data to WebHook receiver.

Supported data format

WebHook receivers are sent in two types of data formats:

  • Key-value dictionary format. Pairs of key-value are sent to WebHook Receivers. Keys are the name of the element blocks of a form, and values are supplied by users.
    {"key":"Your Name","value":"Penguin"},
    {"key":"Tracking code","value":"Da Vinci"},
    {"key":"Your Photo","value":"/contentassets/cc7b5c6ebbb1490aa0839c660ea8f9e2/635817330555935788_cajwhv7s.jpg#@CAJWHV7S.jpg"},
    {"key":"Hidden feed value","value":null},
    {"key":"SYSTEMCOLUMN_SubmitTime","value":"2015-10-29T09:30:55.6755936Z"},
    {"key":"SYSTEMCOLUMN_SubmitUser","value":"giantpenguin"},
  • JSON object format. A JSON object, containing all form data, is sent to WebHook receivers. Keys of the JSON object are the name of element blocks of the form. JSON object format is the default format.
    {
      "requestType"                      : "feature request", 
      "Description"                      : "We need team city to release packages daily.", 
      "emailTitle"                       : "we need one more feature", 
      "toAddress"                        : "Phu.Nguyen@episerver.com", 
      "SYSTEMCOLUMN_FinalizedSubmission" : true, 
      "SYSTEMCOLUMN_HostedPage"          : "174", 
      "SYSTEMCOLUMN_SubmitTime"          : "2016-12-13T14:09:20.733", 
      "SYSTEMCOLUMN_SubmitUser"          : "hung"
    }
    

When a form container is edited and some element blocks are permanently deleted, the submission data might still contain: {"key":"__field_1078","value":""},

Limitation: Because of using the block's name as the field name in SubmissionData, a unique field name is not guaranteed. An editor might name several blocks with same name and it might cause confusion for the WebHook receiver.

Do you find this information helpful? Please log in to provide feedback.

Last updated: Jan 18, 2017

Recommendations [hide]