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 is used to create the unique URI for your webhook trigger. Click Copy to copy the URI and use it to register the webhook in the app you plan to use. TO AVOID RECEIVING EVENTS FROM MULTIPLE SOURCES The event name must be unique across all your webhook recipes. More specifically, the resultant webhook URI 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 to receive from the webhook event. If you use the webhooks wizard, the schema is automatically generated using the sample webhook event as a template. Otherwise, you must add each field to the schema manually. You must define this field when using the following webhook types: GET request PUT/POST with JSON payload PUT/POST with XML payload PUT/POST with FORM encoded payload
	Headers	Describes the headers that you expect from the webhook event. Headers are automatically generated if you use the webhooks wizard, 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 generate all the fields at once. Alternatively, you can add each field 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 custom systems that guarantee an "at least once" delivery of events.

Output fields

Output fields	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, 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 or edit these fields, update the Payload schema input field.

Webhook response

Webhook triggers respond to events with a 200 response code and a JSON payload of {"status":"ok"} by default. 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 situations, the webhook client requires a different structure in one or more parts of the HTTP response. To achieve that, the webhooks connector supports query parameters to change the default response structure.

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. 204 NO CONTENT RESPONSE CODE The 204 response code implies that the response body is empty. This takes precedence and overrides workato_empty_response=false.
workato_empty_response	true/false (default)	Returns an empty response body instead of {"status":"ok"}

The 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"}

Connector webhook URIs

To find the static webhook URI of a Workato connector, navigate to Tools > Connector SDK, select the connector you plan to use, and under Source code > Test code > Static webhook URI, copy the provided link.

Connector webhook URI