Skip to main content

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.

  1. Secret: The Secret parameter (secret), is used for authenticating the user with the CRM tool or service.
  2. Resource: The Resource parameter (resource) denotes the feature or resource offered by the integration or service, such as a Webhook.
  3. 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.

info

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.

info

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:

Webhook

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.

info

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: Webhook

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.

info

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:

Webhook

Example Code

The following is a sample code snippet to show how Operation schema can be implemented in Operation.

info

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

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:

  1. Attach
  2. Detach
  3. Update
  4. Test

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.

info

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.

info

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.

info

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.

info

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