Webhook
Webhooks enable real-time communication between external services and the platform. The webhook schema (webhook.json
file) defines the contract for creating dynamic triggers that respond to external events, allowing workflows to be initiated automatically when specific conditions are met in integrated services.
Schema Structure
The webhook schema consists of several components that define the complete webhook lifecycle:
Parameters Configuration
The parameters section defines the UI elements and validation rules for webhook configuration. This creates a dynamic form that adapts based on user selections and dependencies.
- Field:
"parameters": []
The Parameters section outlines the UI fields visible in the trigger config form. These fields are crucial for setting up the interaction with the service or tool.
- Secret: The Secret parameter (
secret
), is used for authenticating the user with the CRM tool or service. - Resource: The Resource parameter (
resource
) denotes the feature or resource offered by the integration or service, such as a Webhook. - Operation: The Operation parameter (
operation
) lists the potential events or operations provided by the activity or service that will trigger the workflow.
Example Code
The following is a sample code snippet to show how Parameter schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
"parameters": [
{
"name": "secret",
"meta": {...}
},
{
"name": "resource",
"meta": {...}
},
{
"name": "operation",
"meta": {...}
}
]
Secret
The Secret (secret
) is a parameter in the webhook schema, which is responsible for securely storing authentication credentials required to interact with external services.
- Field:
"secret"
Example Code
The following is a sample code snippet to show how Secret schema can be implemented in Parameter.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"name": "secret",
"meta": {
"displayName": "Boltic Account",
"displayType": "autocomplete",
"placeholder": "Select Boltic Account",
"description": "Your credentials are encrypted & can be removed at any time.",
"options": [],
"config": {
"urlType": "secret",
"method": "get",
"url": "/Boltic?current_page=1&page_size=999",
"labelKey": "name",
"valueKey": "_id"
},
"htmlProps": {
"showAddNew": true
},
"validation": {
"required": true
}
}
}
Example Output (Dashboard View)
Once the above integration is configured and triggered, here’s how the feature will appear on the dashboard:
Resource
The Resource is a parameter which specifies the entity in the trigger that the webhook will interact with. It determines the context for the webhook trigger, such as selecting webhook to listen for webhook-related events.
- Field:
"resource"
Example Code
The following is a sample code snippet to show how Resource schema can be implemented in Parameter.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"name": "resource",
"meta": {
"displayName": "Resource",
"displayType": "select",
"options": [
{
"label": "Boltic",
"value": "boltic"
}
],
"validation": {
"required": true
},
"dependencies": {
"conditions": [
{
"field": "secret",
"operator": "NOT_EMPTY"
}
]
}
}
}
Example Output (Dashboard View)
Once the above integration is configured and triggered, here’s how the feature will appear on the dashboard:
Operation
The Operation field defines the specific action or event type that the webhook trigger will listen within the integration. It is a required parameter that determines which set of resources the webhook should respond to, such as customer-related or order-related events. The operation is typically presented as a selectable list, where each option corresponds to a different event category or workflow supported by the external service. The configuration of this field ensures that only relevant triggers are activated based on the user's selection.
- Field:
"operation"
Below is an overview of configuring a new trigger using a schema defined in the Webhook.json file:
Example Code
The following is a sample code snippet to show how Operation schema can be implemented in Parameter.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"name": "operation",
"meta": {
"displayName": "Operation",
"displayType": "select",
"description": "Select the operation you want to perform.",
"options": [
{
"label": "Customer",
"value": "webhook.customer",
"description": "Triggers when a customer-related event occurs, such as creation, update, or deletion."
},
{
"label": "Order",
"value": "webhook.order",
"description": "Triggers when an order event occurs, such as new order creation, fulfillment, update, or deletion."
},
...
],
"validation": {
"required": true
},
"dependencies": {
"conditions": [
{
"field": "secret",
"operator": "NOT_EMPTY"
},
{
"field": "resource",
"operator": "EQUALS",
"value": "webhook"
}
]
}
}
}
Example Output (Dashboard View)
Once the above integration is configured and triggered, here’s how the feature will appear on the dashboard:
Example Code
The following is a sample code snippet to show how Operation schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
"customer": {
"parameters": [
{
"name": "events",
"meta": {
"displayName": "Customers Events",
"description": "The list of triggers based on customers",
"displayType": "select",
"options": [
{
"label": "New Customer",
"value": "customers/create",
"description": "Triggers when a new customer is created in the system."
},
],
"validation": {
"required": true
},
"dependencies": {
"conditions": [
{
"field": "secret",
"operator": "NOT_EMPTY"
},
{
"field": "resource",
"operator": "EQUALS",
"value": "webhook"
},
{
"field": "operation",
"operator": "EQUALS",
"value": "webhook.customer"
}
]
}
}
}
]
},
"order": {
"parameters": [
{
"name": "events",
"meta": {
"displayName": "Order Events",
"displayType": "select",
"description": "The list of triggers based on orders",
"options": [
{
"label": "New Order",
"value": "orders/create",
"description": "Triggers when a new order is created in the system."
},
{
"label": "New Fulfilled Order",
"value": "orders/fulfilled",
"description": "Triggers when an order is marked as fulfilled."
},
],
"validation": {
"required": true
},
"dependencies": {
"conditions": [
{
"field": "secret",
"operator": "NOT_EMPTY"
},
{
"field": "resource",
"operator": "EQUALS",
"value": "webhook"
},
{
"field": "operation",
"operator": "EQUALS",
"value": "webhook.order"
}
]
}
}
}
]
}
Example Output (Dashboard View)
Once the above integration is configured and triggered, here’s how the feature will appear on the dashboard:
Webhook Operations
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:
Attach Operation
The Attach operation registers a webhook endpoint with the external service. It specifies the method used for webhook events. This establishes the communication channel for event notifications. The following schema defines the REST API for attaching a webhook for the specific service.
Example Code
The following is a sample code snippet to show how Attach schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"attach": {
"definition": {
"method": "post",
"url": "https://api.service.com/v1/webhooks",
"headers": {
"Authorization": "Bearer {{secrets.access_token}}",
"Content-Type": "application/json"
},
"body": {
"events": ["{{parameters.events}}"],
"endpoint": "{{webhook.url}}", // Platform-generated webhook URL
"format": "json",
"active": true
},
"response": {
"output": "{{response.data}}",
"error": {
"code": "{{response.status}}",
"message": "{{response.data.error}}"
}
}
}
}
}
Detach Operation
Proper cleanup is essential for webhook management. The detach operation removes webhook registrations when triggers are deleted or modified. The schema below defines the REST API for detaching a webhook for the specific service.
Example Code
The following is a sample code snippet to show how Detach schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"detach": {
"definition": {
"method": "delete",
"url": "https://api.service.com/v1/webhooks/{{webhook.id}}",
"headers": {
"Authorization": "Bearer {{secrets.access_token}}"
},
"response": {
"output": "{{response.data}}",
"error": {
"code": "{{response.status}}",
"message": "{{response.data.error}}"
}
}
}
}
}
Update Operation
For some services, there might be no support for updating a webhook. In such cases, the current webhook is detached, and a new one is created using the attach definition. The following schema defines the REST API for updating a webhook:
Example Code
The following is a sample code snippet to show how Update schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"update": {
"definition": {
"method": "put",
"url": "https://api.service.com/v1/webhooks/{{webhook.id}}",
"body": {
"events": ["{{parameters.events}}"],
"endpoint": "{{webhook.url}}",
"active": true
}
}
}
}
Test Operation
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. The following schema defines a sample REST API for testing the webhook configuration.
Example Code
The following is a sample code snippet to show how Test schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"test": {
"definition": {
"response": {
"output": {
"eventType": "customer.created",
"timestamp": "2024-01-15T10:30:00Z",
"payload": {
"customer": {
"id": "cust_12345",
"email": "[email protected]",
"name": "John Doe",
"status": "active"
}
}
}
}
}
}
}