Webhooks trigger configuration

Configured webhooks trigger

Input fields

Input field		Description
Event name		Name for the event that this webhook trigger is listening to. This name will become part of the unique webhook address generated. This URL is visible below the input field and can be copied. To avoid recipes receiving webhook events from multiple sources, the event name must be unique across all your webhook recipes. More specifically, the resultant webhooks address must be unique across all webhook triggers in a single Workato account.
Payload configuration	Webhook type	Select the type that matches the incoming webhooks. You can select from the following list. GET request PUT/POST with JSON payload PUT/POST with XML payload PUT/POST with FORM encoded payload PUT/POST with raw binary data PUT/POST with unicode text data
	Payload schema	Describe the fields that you expect from the webhook event. If you use the webhooks wizard, this will be automatically generated for you using the sample webhook event as a template. Otherwise, there are two ways to configure this input field. The easier way is to use a sample payload to get all the fields at once. Alternatively, you can add the fields individually. This field needs to be defined only if you choose the following webhook types: GET request PUT/POST with JSON payload PUT/POST with XML payload PUT/POST with FORM encoded payload
	Headers	Describe the headers that you expect from the webhook event. If you use the webhooks wizard, this will be automatically generated for you using the sample webhook event as a template. Otherwise, there are two ways to configure this input field. The easier way is to use a sample JSON to get all the fields at once. Alternatively, you can add the fields individually.
	Deduplication Headers	The X-Workato-Dedup header is an optional webhook header that can be added for any incoming webhook events. The X-Workato-Dedup header allows you to prevent duplicate webhook events from creating duplicate jobs in Workato. If supplied, Workato verifies that this event's X-Workato-Dedup header value has never been seen before for this recipe before creating a job. This is useful for any custom systems that can guarantee "At least once" delivery of events.

Output fields

Input field	Description
Headers	This output object contains datapills of all the headers that you can expect from the webhook events calling this recipe. To add missing headers, just add a field in the Headers input field.
Payload	This output object contains datapills matching the data that you can expect from the webhook events calling this recipe. To add/edit these fields, just update the Payload schema input field.

Webhook response

By default, Workato webhook will respond to events with 200 response code and a JSON payload ({"status":"ok"}). Here is an example:

$ curl 'https://www.workato.com/webhooks/rest/b48a7c64-a7dd-4185-936b-ada1ca84e9fd/foobar' -i
 
HTTP/1.1 200 OK
Date: Wed, 28 Jul 2021 10:03:18 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Server: nginx
Vary: Origin
X-Request-Id: 0b6d7f2ffbfab278c685080aed91d690
X-Correlation-Id: 0b6d7f2ffbfab278c685080aed91d690
Strict-Transport-Security: max-age=31536000; includeSubDomains

{"status":"ok"}

Webhook Validations

• Workato performs validations on JSON based webhooks - denoted by your defined Webhook type, to ensure that the payload is valid JSON. Otherwise, Workato responds with 400 bad request.
• Workato performs validations on JSON/Form/XML/Unicode text based webhooks - denoted by your defined Webhook type, to ensure that the payload is UTF-8 compatible. Otherwise, Workato responds with 400 bad request. If your payload is UTF-8 incompatible, use the Raw Binary Data option for Webhook Type

Custom responses

In some cases, the webhook client requires a different response structure in one or more parts of the HTTP response. To achieve that, the webhooks connector supports query parameters to change the default response.

Query parameter	Accepted values	Description
workato_response_code	Only 2XX codes. Default is 200.	Returns a different response status code. For example, 201 or 204.
workato_empty_response	true/false (default)	Returns an empty response body instead of {"status":"ok"}

::: 204 No Content response code Using 204 response code implies that the response body will be empty. This takes precedence and overrides workato_empty_response=false. :::

This following example uses workato_response_code=201 to return 201 Created as the HTTP response code.

$ curl 'https://www.workato.com/webhooks/rest/b48a7c64-a7dd-4185-936b-ada1ca84e9fd/custom-code?workato_response_code=201' -i

HTTP/1.1 201 Created
Date: Wed, 28 Jul 2021 10:05:03 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 15
Connection: keep-alive
Server: nginx
Vary: Origin
X-Request-Id: b23380f48d02c38fa761e8afa4b94862
X-Correlation-Id: b23380f48d02c38fa761e8afa4b94862
Strict-Transport-Security: max-age=31536000; includeSubDomains

{"status":"ok"}