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 > Custom Webhook instant trigger module 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.
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 in the scenario. To enable the option to map items outputted from the webhook, Integromat needs to determine the data structure of the incoming payload so the other modules know what to expect from the webhook. That's why Integromat will ask you to send sample data to the displayed address:
There are two ways to supply the sample data:
If you would like to use the second option, follow these steps:
URL | url of the webhook |
Method | POST |
Body type | Raw |
Content type | JSON (application/json) |
Request content | raw JSON expected in the webhook |
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.
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.
GET https://hook.integromat.com/yourunique32characterslongstring?name=Integromat&job=automate
POST https://hook.integromat.com/yourunique32characterslongstring
Content-Type: application/x-www-form-urlencoded
name=Integrobot&job=automate
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 multipart/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.
POST https://hook.integromat.com/yourunique32characterslongstring
Content-Type: application/json
{"name": "Integrobot", "job": "automate"}
PRO TIP: If you wish to access the original JSON, open the webhook's settings:
and enable the "JSON pass-through" option:
Content-Length
) is 5 MB (5.242.880 bytes) regardless of the subscription tier.To access the webhook's headers, enable the Get request headers option in the webhook's setup:
You can than extract a particular header value with the combination of map()
& get()
functions. The example below shows a formula that extracts the value of the authorization
header from the Headers[]
array. The formula is used in a filter that compares the extracted value with the given text to pass only webhooks if there is a match.
See Mapping an array's element with a given key for further information on obtaining an array's element with a given key.
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:
These are default responses when the scenario does not contain the Webhook Response module:
HTTP status code | Body | |
Webhook accepted in the queue | 200 | Accepted |
Webhook queue full | 400 | Queue is full. |
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.
These are additional default responses when the scenario does contain the Webhook Response module:
HTTP status code | Body | |
Scenario encounters an error | 500 | Scenario failed to complete. |
Timeout for sending a response is 40 seconds. If the response is not available within that period, Integromat returns a '200 Accepted' status.
Configure the Webhook Response module as follows:
Status | 2xx success HTTP status code, e.g. 200 |
||||
Body | HTML code, e.g.:
<!DOCTYPE html> |
||||
Custom headers |
|
It will produce an HTML response that will be displayed like this in a web browser:
Configure the Webhook Response module as follows:
Status | 3xx redirection HTTP status code, e.g. 303 |
||||
Custom headers |
|
Please see the Custom Mailhook documentation.
If some items are missing in the mapping panel in the setup of the modules following the Webhooks > Custom Webhook module, click on the Webhooks > Custom Webhook module to open its setup and click on the "Re-determine data structure" button:
Then follow the steps described in the section Determine the webhook's data structure.