Webhooks

Webhooks power up Instant Triggers, which execute the flow immediately after the remote server sends data.

In order to work with webhooks, you always need to create an Instant Trigger and pair it with a webhook.

Specification

Specifies how to get data from the payload and how to reply to a remote server.

{
    "verification": {
        "condition": String|Boolean,
        "respond": {
            "type": Enum[json, urlencoded, text],
            "status": String|Number,
            "headers": Object
            "body": String|Object,
        }
    },
    "respond": {
        "type": Enum[json, urlencoded, text],
        "status": String|Number,
        "headers": Object
        "body": String|Object,
    },
    "iterate": {
        "container": String,
        "condition": String|Boolean
    },
    "output": String|Object,
    "condition": String|Boolean,
    "uid": String
}

Note: If the webhook returns multiple items in one batch, you might need to use the iterate directive to specify which items to output. Then you might want to specify the output directive to map items to output. If you do not specify the output directive, items will be returned as-is.

Key	Type	Description
respond	Response Specification	Specifies how to respond to the remote server
verification	Verification Specification	Specifies how to reply to the remote server, if it needs a confirmation
iterate	IML String or Iterate Specification	Specifies how response items (in case of multiple) are retrieved and processed.
output	Any IML Type	Describes structure of the output bundle.
condition	IML String or Boolean	Determines if to execute current request or never.
uid	IML String	Specifies how to get the user ID from the request body.

respond

Required: no

This directive lets you customize Integromat’s response on the webhook or a verification request.

Key	Type	Required	Specification
type	IML String	no	Specifies how to encode data into body. Default: json. Available values: json, urlencoded, text.
status	IML String	no	Specifies the HTTP status code that will be returned with the response.
headers	IML Flat Object	no	Specifies custom headers that are to be sent with the response.
body	Any IML Type	no	Specifies the response body.

verification

Required: no

This directive allows you to reply to webhook verification requests. Some systems will not allow you to create webhooks prior to verifying that the remote side (in this case Make) is prepared to handle them. Such systems may send a code and request Make to return it and may be some other value with it. In such case, this directive will help you.

Key	Type	Description
condition	IML String	Specifies how data are serialized into body.
respond	IML String	Specifies the response status code.

Example:

{
    "verification": {
        "condition": "{{if(body.code, true, false)}}",
        "respond": {
            "status": 202,
            "type": "json",
            "body": {
                "code": "{{body.code}} | 123abc"
            }
        }
    }
}

condition

Required: no Default: true

This directive distinguishes normal webhook requests from verification requests. Usually, the remote service will send some kind of code to verify that Integromat is capable of receiving data. In such case, you may want to check for the existence of this code variable in the request body. If it exists - this means that this request is a verification request. Otherwise, it may be a normal webhook request with data.

respond

Required: no

This directive is exactly the same as the respond directive, except that it is nested in verification. The behavior of verification.respond, is the same as normal respond.

iterate

Properties of the iterate directive are described in the Communication docs. Read more.

output

Properties of the output directive are described in the Communication docs. Read more.

condition

Properties of the condition directive are described in the Communication docs. Read more.

uid

Required: only in shared webhooks

Specifies how to get the user ID from the request body. This value is then used to search for the recipient of the message in the database of connections. Don't forget to specify the uid parameter in the connection definition.

Available IML variables

These IML variables are available for you to use everywhere in a webhook:

• now - Current date and time

• environment - TBD

• parameters - Contains webhook’s input parameters.

• data - Alias for parameters.

• body - Contains the body of an incoming webhook.

• query - Contains query string parameters of an incoming webhook.

• method - Contains HTTP method of an incoming webhook.

• headers - Contains headers of an incoming webhook.

Types of webhooks

Shared

Shared webhooks come to use when the service sends all the notifications for all the users to only one registered URL.

pageShared

Dedicated

Unlike a shared webhook, a dedicated webhook is directly linked to the user account. Only notifications for the specific user are received.

pageDedicated