Webhook Response

In most integration scenarios only the response code will matter. However some external systems have a verification phase (e.g. Sharepoint) as an additional security layer before allowing a webhook integration. You can pass such a phase by configuring the shape of the webhook response body based on the data from the request.

Content type#

The response header will be set accordingly. The selected content type will also determine how the body template is interpreted.

  • application/json - All response template expressions will be evaluated to the JSON representation of the referenced data.
  • text/plain - Response template expressions referencing primitive values will be evaluated as text, nested structures and lists will be discarded.

Response Template#

Configure the response body using our simple template syntax. You can construct a response which will get data from the request query string, headers, body or any combination of them.

  • ${Webhook::Query}
  • ${Webhook::Headers}
  • ${Webhook::Body}

For example given the request data

// Request Url
https://app.cozyroc.cloud/webhook/v28gX9/904E393C7D6080954B54AF5D1CCD8A81632CDE01739B2409DE10D6A7499BB22E?validationToken=4B54AF5D1CCD8A81632CDE01739
// Request Headers
Authorization: auth 30f9653d1d15460a9cc58d082b7981bf
// Request Body
{
"OrderId" : 145,
"Amount" : 5,
"Customer": {
"Id" : 148,
"Name": "John Smith"
}
}

and response template

{
"validationToken": ${Webhook::Query.validationToken},
"authorization": ${Webhook::Headers.Authorization},
"amount": ${Webhook::Body.Amount},
"customer": ${Webhook::Body.Customer}
}

, the response body for application/json will be

{
"validationToken": "4B54AF5D1CCD8A81632CDE01739",
"authorization": "auth 30f9653d1d15460a9cc58d082b7981bf",
"amount": 5,
"customer": {
"Id" : 148,
"Name": "John Smith"
}
}

while for text/plain it will be

{
"validationToken": 4B54AF5D1CCD8A81632CDE01739, // Text value no double quotes
"authorization": auth 30f9653d1d15460a9cc58d082b7981bf, // Text value no double quotes
"amount": 5,
"customer": // Complex object discarded
}

Example#

In this section we are going to configure a webhook to pass the SharePoint verification phase.

According to the SharePoint documentation when a new subscription is created, SharePoint will send a request to the registered URL similar to:

POST https://app.cozyroc.cloud/webhook/v28gX9/904E393C7D6080954B54AF5D1CCD8A81632CDE01739B2409DE10D6A7499BB22E?validationtoken={randomString}
Content-Length: 0

For the subscription to be created successfully, your webhook must respond with the validationtoken query string parameter as a plain-text response:

HTTP/1.1 200 OK
Content-Type: text/plain
{randomString}
  1. Add a webhook trigger for a package.

  2. In the response section of the webhook page select content type text/plain.

  3. Set the response to

${Webhook::Query.validationtoken}

Your configuration should look like this img

  1. Save the webhook and configure the integration in SharePoint.