Webhooks

Webhooks are used with instant triggers that execute the flow immediately after the remote server sends data.

To use webhooks, you must always create an instant trigger and link it to a webhook.

Specification

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

Code

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

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. Used for webhooks that require a verification mechanism, such as challenge responses.
iterate	IML string or iterate specification	Specifies how the response items (in case of multiple) are retrieved and processed.
output	Any IML type	Describes the structure of the output bundle.
condition	IML string or boolean	Determines whether to execute the current request.
uid	IML string	Specifies how to get the user ID from the request body. Necessary to associate the recipient when using a shared webhook.

respond

Required: no

This directive lets you customize Make's response on the webhook or a verification request.

Key	Type	Required	Description
type	IML string	no	Specifies how to encode data into the 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 issue a verification request during webhook creation to ensure your webhook is prepared to handle incoming data. Such systems may send a code and request Make to return it and maybe some other value with it. In such case, this directive will help you.

Key	Type	Description
condition	IML string	Specifies when to treat the incoming data as a verification request.
respond	IML string	Specifies the response.

Code

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

verification.condition

Required: no

Default: true

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

verification.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 the normal respond.

iterate

Properties of the iterate directive are described in the communication documentation.

output

Properties of the output directive are described in the communication documentation.

condition

Properties of the condition directive are described in the communication documentation.

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. Remember 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:

Variable	Description
now	Current date and time
environment	TBD
parameters	Contains the 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 are used when the external service sends all events from all users to a single URL that you control. With this, the user is not able to see the URL and you must use the uid in the connection and in the webhook communication to associate the payloads to the right users.

Dedicated

​Dedicated webhooks are the most common type. An individual URL is created and either automatically registered to the external platform or the user may need to configure it manually. The user can see the URL and copy it from the scenario.