Post to Webhook Action

Overview

A Webhook is a simple HTTP publish and subscription model for passing information between services. With the Webhook action you can call your own HTTP endpoint when a form is submitted and optionally include form answers. This means all your connector logic can remain in an external service that can be updated and load balanced separately.

The service call is made as a POST and the body of the request contains the JSON payload. Service response codes determine if the action is considered to have failed or completed. This action does not deal with generated documents.

Manage

There are 2 Manage level connector settings that provide the defaults for all the Webhook actions to be used in the account.

Default Webhook URL Endpoint: The URL of your service, must be accessible via the web server.

Default Secret Key: User provided API key that is sent to and validated by your service. Prevents other people calling your service.

Design

The action appears as "Post to Webhook" and it has 3 inputs and 2 outputs.

Inputs

Webhook URL Endpoint: The URL of your service.

Answer Values: Optional values and question references that you want to send to your service. Same format as the SQL Server action's parameters, @name=[q1]

📘

Note

Only Fixed Value are supported in Answer Values. Other reference types - Data Question and Answer value are not supported

Secret Key: User provided API key that is sent to and validated by your service.

Outputs

Response Body Output: The HTTP response body that was returned from your service.

Response Code Output: The HTTP response code that was returned from your service.

Example Payload

{
  "action": "My Action Name",
  "created": "2015-11-24T04:34:46.8659932Z",
  "secretKey": "MySecret",
  "sender": {
    "userGuid": "405f36cf-81e0-4c4d-b08a-197d97a195e3"
  },
  "project": {
    "projectName": "Webhook",
    "projectGroupGuid": "d74f6aa1-1039-4ad7-9646-c3ea68a1fdca",
    "runId": "00e32b92-0b20-4b28-a3b0-64555431d6ee"
  },
  "values": {
    "q1": "1",
    "q2": "2",
    "myValue": "abcdef"
  }
}

Example WebAPI Endpoint

using Newtonsoft.Json.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
 
namespace WebApplication2.Controllers.Api
{
  public class WebhookController : ApiController
  {
    public HttpResponseMessage Post([FromBody] JObject data)
    {
      if ((string)data["secretKey"] != "MySecret")
      {
          return new HttpResponseMessage(HttpStatusCode.Forbidden);
      }
 
      // Process data[values] dictionary
 
      return new HttpResponseMessage(HttpStatusCode.OK);
    }
  }
}

Webhook Action - Custom Headers

New input to the Webhook action called "Custom Headers". It works exactly the same as the REST custom headers. The values will be sent with the POST to the external service.

Documents can now also be sent with the POST request. This is configured the same as other actions, the documents tab in Design controls what files will be sent. On upgrade of an existing project the action documents will be changed "All" to "Custom" to preserve functionality.

When documents are being sent there will be a root "documents" array containing the name and the binary.

{
  "documents": [
    {
      "name": "Document1.docx",
      "binary": "Base64 string"
    }
  ]
}