Webhook Schema

The Webhook.json file is used only for activities configured as triggers within the platform. This setup allows for dynamic creation of triggers based on real-time data or events.

Below is an overview of configuring a new trigger using a schema defined in the Webhook.json file:

Configuration Process

To set up a new trigger, you need to provide a schema that describes the trigger's behavior and parameters. This schema includes several key components outlined below:

{
    "form_submission": {
        "parameters": [
            {
                "name": "site_id",
                "meta": {
                    "displayName": "Webflow Site",
                    "displayType": "select",
                    "options": [],
                    "placeholder": "",
                    "description": "Select the site that you would like to receive notifications from.",
                    "value": "",
                    "validation": {
                        "required": true
                    },
                    "config": {
                        "urlType": "options",
                        "method": "post",
                        "url": "integrations/options",
                        "body": {
                            "name": "webflow",
                            "resource": "webhook",
                            "operation": "webhook.form_submission",
                            "secret": "{{parameters.secret}}",
                            "loadOptionsMethod": "getSites",
                            "webhook": true
                        },
                        "labelKey": "displayName",
                        "valueKey": "id"
                    },
                    "dependencies": {
                        "conditions": [
                            {
                                "field": "secret",
                                "operator": "NOT_EMPTY"
                            },
                            {
                                "field": "resource",
                                "operator": "EQUALS",
                                "value": "webhook"
                            },
                            {
                                "field": "operation",
                                "operator": "EQUALS",
                                "value": "webhook.form_submission"
                            }
                        ]
                    }
                }
            }
        ],
        "attach": {
            "definition": {
                "body": {
                    "filter": {
                        "id": "{{parameters.form_id}}"
                    }
                }
            }
        }
    },
    "getSites": {
        "definition": {
            "method": "get",
            "url": "https://api.webflow.com/v2/sites",
            "headers": {
                "Accept": "application/json",
                "Authorization": "Bearer {{secrets.access_token}}"
            },
            "qs": {
                "limit": 100
            },
            "response": {
                "output": "{{response.data.sites}}",
                "error": {
                    "code": "{{response.status}}",
                    "message": "{{response.data.message}}"
                }
            }
        }
    }
}

Form Submission (form_submission)

For operations, you can define a custom payload body that will be passed with an API call. The schema allows for detailed configuration of the parameters involved in the operation.

Parameters (parameters)

This section outlines the UI fields visible in the Activity Config form UI. These fields are crucial for setting up the interaction with the service or tool.

Attach Operation (attach)

Specifies the method used for webhook events. The following schema defines the REST API for attaching a webhook for the specific service.

{
    "attach": {
        "definition": {
            "method": "post",
            "url": "https://api.webflow.com/v2/sites/{{parameters.site_id}}/webhooks",
            "headers": {
                "Accept": "application/json",
                "Content-Type": "application/json",
                "Authorization": "Bearer {{secrets.access_token}}"
            },
            "body": {
                "triggerType": "{{parameters.operation}}",
                "url": "{{webhook.url}}"
            },
            "response": {
                "output": "{{response.data}}",
                "error": {
                    "code": "{{response.data.code}}",
                    "message": "{{response.data.message}}"
                }
            }
        }
    }
}

Detach Operation (detach)

The schema below defines the REST API for detaching a webhook for the specific service.

{
    "detach": {
        "definition": {
            "method": "delete",
            "url": "https://api.webflow.com/v2/webhooks/{{webhook.id}}",
            "headers": {
                "Accept": "application/json",
                "Authorization": "Bearer {{secrets.access_token}}"
            },
            "response": {
                "output": "{{response.data}}",
                "error": {
                    "code": "{{response.data.code}}",
                    "message": "{{response.data.message}}"
                }
            }
        }
    }
}

Update Operation (update)

For some services, there might be no support for updating a webhook. In such cases, the current webhook is deleted, and a new one is created using the attach definition. The following schema defines the REST API for updating a webhook:

{
    "update": {
        "definition": {
            "method": "post",
            "url": "https://api.webflow.com/v2/sites/{{parameters.site_id}}/webhooks",
            "headers": {
                "Accept": "application/json",
                "Content-Type": "application/json",
                "Authorization": "Bearer {{secrets.access_token}}"
            },
            "body": {
                "triggerType": "{{parameters.operation}}",
                "url": "{{webhook.url}}" // This URL is generated automatically and sent to the service when attaching or updating a webhook. It is used by the integration or service to trigger the workflow when a specific event occurs.
            },
            "response": {
                "output": "{{response.data}}",
                "error": {
                    "code": "{{response.data.code}}",
                    "message": "{{response.data.message}}"
                }
            }
        }
    }
}

Test Operation (test)

The following schema defines a sample REST API for testing the webhook configuration. The test operation is essential for ensuring that the webhook is correctly set up and that the payload is passed to subsequent activities in the workflow.

{
    "test": {
        "definition": {
            "method": "",
            "url": "",
            "headers": {},
            "response": {
                "output": {
                    "triggerType": "form_submission",
                    "payload": {
                        "name": "Email Form",
                        "siteId": "6699e3da4a1c01e3ff5cac2c",
                        "data": {
                            "Name": "Sample Authentication Secret",
                            "Email": "[email protected]"
                        },
                        "submittedAt": "2024-08-26T08:44:35.912Z",
                        "id": "66cc40731222bf0a5d56ebb9",
                        "formId": "669f7c029f5a0daec3767942",
                        "formElementId": "4c266e2e-7484-6574-3dcf-01cde8ede7c3"
                    }
                },
                "error": {}
            }
        }
    }
}

• On the canvas, for Cloud Triggers, you will see a play button. Clicking on it will send a sample payload structure that will be passed from the trigger to subsequent activities.

• This helps users to utilize the payload and the keys within it in connected activities.

This structured approach ensures that you can efficiently configure and manage webhooks as triggers, tailoring them to specific operations and integrating seamlessly with external systems.