webhook.jsonc
The Webhook.jsonc 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 how to configure a new trigger using a schema defined in the Webhook.jsonc 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:
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.
- Secret: The first field, typically named
secret, is used for authenticating the user with the CRM tool or service. - Resource: The second field denotes the feature or resource offered by the integration or service, such as a Webhook.
- Operation: The third field lists the potential events or operations provided by the activity or service that will trigger the workflow.
- Secret: The first field, typically named
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.
{
"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}}"
}
}
}
}
}
Explanation of Each Field:
- form_submission: Denotes the operation.
- attach: Specifies the method used for webhook events.
- definition: Outlines the REST API definitions.
- body: Includes custom changes as required. Otherwise, use the definition provided at the root level of attach, detach, and delete.
- name: It should match the Activity name.
- resource: Name of the feature that is available with the activity/service, e.g., account.
- operation: The event that triggers the webhook.
- secret: Unique authentication details stored by the user for the specific integration.
- loadOptionsMethod: Dynamically loads options in select or autocomplete using REST API definition. Assign the method name that handles the API call. In the example above, it is
getSites, which is defined at the resource level. - webhook: A custom flag that needs to be passed in the API to differentiate between triggers and activities.
Attach Operation
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
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
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
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.