Webhooks

Integromat Updated October 15, 2018 22:09

Creating custom webhooks

Any application that is connected to the Internet and allows the sending of HTTP requests can send webhooks to Integromat. To connect such an app to Integromat, add the Webhooks trigger Custom webhook to your scenario. When setting this trigger, click on the Add button next to the Webhook field and enter a name for the new webhook.

PRO TIP: Once you create a webhook, you can use it in more than one scenario at the same time. Each scenario may contain different modules and have a different schedule. The data is duplicated, that's why the individual scenarios do not influence each other.

Once you create a webhook, you will see a unique URL that Integromat will listen for. The data sent to this address is first validated and then passed on for processing to the scenario. But, before you can start mapping variables, it is necessary for Integromat to determine the data structure of the incoming payload. So, once you create a new webhook, Integromat will ask you to send some sample data to the displayed address. Once Integromat analyzes your data sample, you'll be able to map variables from incoming payloads to any subsequent module.

IMPORTANT: At the moment of delivering a webhook notification, there must be at least one scenario that listens for this webhook data. If the scenario is not active, the data is stored in the queue. Once you activate the scenario, all bundles waiting in the queue will be processed sequentially.

Supported incoming data formats

Integromat supports 3 formats of incoming data - Query String, Form Data and JSON. Integromat validates all incoming data against the selected data structure and then depending on the settings of the scenario, the data is either stored in the queue for processing or processed immediately.

If any part of the data does not pass the validation, Integromat returns a '400 HTTP' status code and specifies in the body of the HTTP response the reason why the incoming data failed the validation checks. If the validation of the incoming data succeeds, Integromat returns a '200 Accepted' status in response.

Incoming data examples

Query String

GET https://hook.integromat.com/yourunique32characterslongstring?name=Integromat&job=automate

Form Data

POST https://hook.integromat.com/yourunique32characterslongstring
Content-Type: application/x-www-form-urlencoded

name=Integrobot&job=automate

Multipart

POST https://hook.integromat.com/yourunique32characterslongstring
Content-Type: multipart/form-data; boundary=---generatedboundary

---generatedboundary
Content-Disposition: form-data; name="file"; filename="file.txt"
Content-Type: text/plain

Content of file.txt
---generatedboundary
Content-Disposition: form-data; name="name"

Integromat
---generatedboundary

In order to receive files encoded with mutlipart/form-data, it is necessary to configure a data structure with a collection type field that contains the nested fields name, mime and data. The field name is a text type and contains the name of the uploaded file. The mime is a text type and contains a file in the [MIME] format (https://en.wikipedia.org/wiki/MIME). The field data is a buffer type and contains binary data for the file being transferred.

JSON

POST https://hook.integromat.com/yourunique32characterslongstring
Content-Type: application/json

{"name": "Integrobot", "job": "automate"}

Responding to webhooks

The default response to a webhook call contains just a simple text "Accepted" and the response is returned to the webhook's caller right away during the execution of the Custom webhook module. You can easily test it like this:

1. Place a Custom webhook module in your scenario.
2. Add a new webhook in the module's configuration.
3. Copy the webhook's URL to clipboard.
4. Run the scenario - the Custom webhook module should be waiting for the webhook call (see on the right)
5. Open a new browser window, paste the copied URL in the address bar and press Enter.
6. The Custom webhook module will be triggered and the browser will display the following page:

If you wish to customize the webhook's response, employ the module Webhook response. The configuration of the module contains two fields: Status and Body. The Status field should contain HTTP response status codes like 2xx for Success (e.g. 200 for OK), 3xx for Redirection (e.g. 307 for Temporary Redirect), 4xx for Client errors (e.g. 400 for Bad Request), etc. The Body field should contain anything that will be accepted by the webhook's call. It can be a simple text, HTML, XML, JSON, etc. It is advisable to set the Content-Type header to the corresponding mime type: text/plain for plain text, text/html for HTML, application/json for JSON, application/xml for XML, etc.

HTML Response example

The following configuration of the Webhook response module:

It will produce an HTML response that will be displayed like this in a web browser: