Webhook - Reference Documentation

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

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

Index

• Specification
  • respond
    • status
    • type
    • headers
    • body
  • verification
    • condition
      • condition
      • default
    • respond
  • iterate
    • container
    • condition
  • output
  • condition
• Webhook registration
  • Attach
  • Detach

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": String,
    or
    "iterate": {
        "container": String,
        "condition": String|Boolean
    },
    "output": String|Object,
    "condition": String|Boolean
}

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.

respond

Required: no
Default: empty

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

respond.type

Required: no
Default: json
Values: json, urlencoded, text

This directive specifies how to encode data into body.

respond.status

Required: no
Default: empty

This directive specifies the HTTP status code that will be returned with the response.

respond.headers

Required: no
Default: empty

This directive specifies custom headers that are to be sent with the response.

respond.body

Required: no
Default: empty

This directive specifies the response body.

verification

Required: no
Default: empty

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 Integromat) is prepared to handle them. Such systems may send a code and request Integromat to return it and may be some other value with it. In such case this directive will help you.

Example:

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

verification.condition

Required: no
Default: empty

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 verification request. Otherwise it may be a normal webhook request with data.

verification.respond

Required: no
Default: empty

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

iterate

Required: no
Default: empty

This directive specifies the container of an array of items that the module must process and output. In its simplest form iterate directive is an IML String, which points to a container of your items (must be an array):

{
    "iterate": "{{body.data}}"
}

When you need to filter out some items from processing, you are able to specify the iterate directive as an object, in which case it will have the following properties:

iterate.container

Required: yes
Default: empty

The iterate.container directive must point to an array of items that are to be processed.

iterate.condition

Required: no
Default: empty

An optional expression to filter out unwanted items. Must resolve into a Boolean value, where true will pass the item through, and false will drop the item from processing. The item variable is available in this directive, which represents the current item being processed.

Important:
The iterate directive changes the behaviour of the output directive and allows you to use a special variable item that represents the currently processed item. The output directive will be executed for each item in the container that you have specified in iterate.container. You are able to use the item variable in the output directive to access properties of iterated objects.

For example you are iterating this response:

{
    "success": true,
    "data": [{
        "id": 1,
        "foo": "bar"
    }, {
        "id": 2,
        "foo": "baz"
    }, {
        "id": 3,
        "foo": "qux"
    }]
}

Then, in order to process all items contained in the data array, you would specify your iterate directive like so:

{
    "iterate": "body.data",
    "output": {
        "id": "{{item.id}}",
        "text": "{{item.foo}}"
    }
}

Here, in the output directive, you specify how you wish your output to look. The item variable represents the currently processed item from the data array. The output of this module will then be:

[{
    "id": 1,
    "text": "bar"
}, {
    "id": 2,
    "text": "baz"
}, {
    "id": 3,
    "text": "qux"
}]

output

Required: no
Default: body, when iterate is not set; item otherwise

With the output directive you can specify how you want your module output to look. When using iterate, output is processed for each item of the array, that was specified with the iterate directive. When not using iterate, output is executed only once and the result is fed to the wrapper directive, if present, otherwise it will be the final result of the module.

condition

Required: no
Default: true

This directive specifies if the webhook should be processed or not.

If this directive is not specified - the webhook will always pe processed.

When you need to return some data when the condition is false, you are able to specify the condition directive as an object, in which case it will have the following properties:

condition.condition

Required: no
Default: empty

The original condition directive. If the condition is not specified, the request is always executed.

condition.default

Required: no
Default: empty

An optional module output when the condition is false.

Webhook registration

Registration can be handled either manually by the user or automatically via special Attach and Detach remote procedures.

Attach

The Attach remote procedure is used to automatically attach a webhook to a remote service. Please note that you will need to detach this RPC later, and for that you will need this remote procedure’s Id.

{
    "url": "https://www.example.com/api/webhook",
    "method": "POST",
    "body": {
        "url": "{{webhook.url}}"
    },
    "response": {
        "data": {
            "externalHookId": "{{body.id}}"
        }
    }
}

To save the remote webhook id (in order for detach to work), you must use the response.data collection. This collection will be available in the detach webhook remote procedure as webhook IML variable for you to use.

The webhook collection with webhook’s data is also accessible in regular remote procedure calls if the call is processed in context of an Instant Trigger. For example if you create a dynamic interface for an Instant Trigger based on parameters entered when webhook was created.

Detach

The Detach remote procedure is used to automatically detach (delete) a webhook from a remote service when it is no longer needed. The only thing you have to do is to correctly specify the url to detach a webhook. No response processing is needed.

{
    "url": "https://www.example.com/api/webhook/{{webhook.externalHookId}}",
    "method": "DELETE"
}