Webhooks actor

📘

Note

Optimizely Forms is only supported by MVC-based websites and HTML5-compliant browsers.

A webhook is a simple event notification through HTTP POST; when a webhook event is triggered, an HTTP POST request is sent to a URL.

Optimizely has built-in webhooks inspired by GitHub webhook specs. As a publisher of the event, webhooks pings remote URLs, pushes enough information, and sends 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 data format used before sending data to the webhook receiver.

Supported data format

WebHook receivers are sent in two types of data formats:

• Key-value dictionary format – Key-value pairs are sent to webhook receivers. Keys are the name of the element blocks of a form, and users supply values.
  C#

  {"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 form data is sent to webhook receivers. Keys of the JSON object are the names of element blocks of the form. JSON object format is the default format.
  C#

  {
    "requestType"                      : "feature request", 
    "Description"                      : "We need team city to release packages daily.", 
    "emailTitle"                       : "we need one more feature", 
    "toAddress"                        : "[email protected]", 
    "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.