The Webhook action in SmartSuite empowers you to integrate seamlessly with external systems by sending data through an outbound REST API request. This action supports various HTTP methods such as GET, POST, PUT, PATCH, and DELETE, enabling interaction with numerous third-party platforms.
Plan Availability | All plans |
Permissions | Admin, Solution Manager |
Related Reading |
What is an Action?
In SmartSuite automations, an action is the "then" part of an automation sequence. It specifies the task performed when a certain event (trigger) occurs and conditions are met. Actions range from simple tasks like updating records to more complex ones like triggering webhooks or syncing data with external systems.
Configuring the Webhook Action
Follow these steps to configure the Webhook action:
1. Specify the Webhook URL
Enter the external endpoint in the URL field where you want to send the data. SmartSuite validates the URL format to ensure accuracy and restricts internal SmartSuite addresses to prevent misdirected requests.
2. Choose the HTTP Method
Select the appropriate HTTP method for your request:
GET (default)
POST
PUT
PATCH
DELETE
For methods like POST, PUT, and PATCH, additional fields for headers and request payloads will appear.
3. Define Headers and URL Parameters
Headers: Add custom headers by specifying key-value pairs. The default
Content-Typeis "application/json," but you can add others (e.g., authorization tokens or API keys).Use the
+icon to map field values into header values dynamically.
URL Parameters: Specify key-value pairs that are appended to the request URL.
4. Configure the Payload (Request Content)
For POST, PUT, or PATCH requests, define the payload content:
Select content type (e.g., JSON Object or Text). See Structuring JSON Data below for more details.
Build complex content structures, including nested objects.
5. Handle the Response
Capture the response data from the webhook action for use in subsequent automation steps:
Automatic Response Parsing (Coming Soon): SmartSuite will automatically parse response content, allowing you to map values directly to fields.
Manual Response Parsing: Paste sample response data and manually configure mappings, especially useful for static responses.
See Structuring JSON Data below for more details.
6. Use Response Codes
HTTP response codes (e.g., 200 for success, 404 for not found) are passed as numeric values to subsequent automation steps. Use these codes to trigger additional actions based on the request’s success or failure.
7. Timeout
Webhook requests have a 30-second timeout to prevent delays in workflows caused by long-running actions.
8. Testing and Debugging
Ensure your webhook is properly configured by:
Sending a sample request to test the setup.
Viewing detailed request and response data for debugging.
Re-testing after making configuration changes.
Structuring JSON Data
When working with request bodies and response payloads in SmartSuite, you have full control over defining the structure of the data you send or expect to receive. SmartSuite supports the following data types:
JSON Object – A structured key-value collection of data.
JSON Array – An ordered list of values.
Text – A string-based value.
Boolean – A
trueorfalsevalue.Number – A numeric value (integer or decimal).
Defining the Content Type
Start by selecting the appropriate content type for your request or response payload. If you choose JSON Object or JSON Array, you can further customize the structure by adding additional fields to define the data format.
Adding JSON Properties
To extend your JSON Object or Array with custom properties, click “Select Field” and choose the appropriate data type. Each property requires:
A unique key name – Defines the property’s identifier within the JSON structure.
A value source – You can assign a static value or dynamically source content from fields in the trigger record or a previous automation action.
This flexibility allows you to build well-structured, dynamic JSON payloads tailored to your workflow needs.
Example - JSON Object
Let’s say that you need to send a JSON object with information from a project to an external system. You want to send the Record ID of the project, its due date, the status value and a boolean value indicating that the external system should set “complete” to true.
The Request Content to do this looks like this:
Advanced Structures: Arrays
You can configure arrays in the JSON output, which can contain simple types or objects. When your Webhook (an HTTPS request to any REST endpoint) returns a JSON payload containing an array of objects, you can surface that array directly as an output—and then feed it straight into a Looping action to process each object individually.
Step 1: Define Your Webhook Action
In your automation, add a Webhook action.
Enter the HTTP method and target URL for your API.
Click Test to fetch a sample response and inspect the structure.
Step 2: Expose the Array Output
In the Response Content section, choose
JSON Objectas the response type.Locate the array in your JSON structure (in this case, the
itemsarray).Select the fields you want to expose from the array’s objects. Based on the screenshot, the object contains:
id: Numbername: Textenabled: Boolean
Click + Select Field if you want to expose additional fields from each object.
Step 3: Use the Output in a Looping Action
Add a Looping action below your Webhook action.
Choose the array you defined (
items) as the Input List.Inside the Looping group, use Current item to access fields like
id,name, orenabled. These will appear in dropdowns for field mapping in subsequent steps.
Example
If your Webhook response looks like this:
jsonCopyEdit{ "items": [ { "id": 1, "name": "Alpha", "enabled": true }, { "id": 2, "name": "Beta", "enabled": false } ] }The Webhook action will expose
itemsas a JSON Array of ObjectsYou can configure
id,name, andenabledas accessible fieldsA Looping action can iterate through each object, treating them as individual records to process in downstream actions
This feature is ideal for processing structured data from external APIs, like task lists, user directories, or integration payloads—streamlining your automations and enabling far more dynamic workflows.
Practical Use Cases and Scenarios
1. CRM Integration
Scenario: Send customer data to an external CRM system.
Solution: Configure a POST request to transfer contact details and track the response for success or errors.
2. Notification Systems
Scenario: Trigger notifications in communication apps like Slack or Teams.
Solution: Use a webhook to send a formatted message payload to the app’s webhook URL.
3. Project Management Tools
Scenario: Update project task statuses in an external tool.
Solution: Configure PUT requests to update tasks with field values dynamically mapped from SmartSuite.
Webhook actions simplify complex integrations and enhance automation capabilities. Use them to streamline workflows, eliminate manual tasks, and ensure seamless data exchange between SmartSuite and your tech stack.
Related Feature Videos