SmartSuite’s Incoming Webhook trigger makes it simple to start automations from external sources, like third-party services or custom code, by sending an HTTP request to a unique SmartSuite-generated URL. Configure your webhook, test it, and map its payload fields to use in subsequent automation steps.
Feature Overview Video
Plan Availability | All plan types |
Permissions | Administrators, in any solution, and Solution Managers, in the solutions they manage, create and manage automations. |
Platform | Web |
Related Reading |
My webhook did not start the automation: check these six things, in order
Administrators and Solution Managers can open History and change the automation. If you have neither role, send this page, the time of the request and the response code your system received to the person who manages the solution.
The automation is disabled. While it is disabled SmartSuite only logs incoming requests for testing; it runs nothing. Your system still receives a success response ([success: true]), so it cannot tell that the automation is off. Enable it in Step 5: Enable & Finalize.
The request was rejected. Open History and select Details on the run. A request in the wrong form shows Error with the reason, for example Method GET not allowed, expected method: POST. The causes are the wrong HTTP method (405), a body not sent as UTF-8 application/json (415), malformed JSON (400) or a payload over 1 MB (413). A request without a required field shows Rejected (Rejected without running) with Missing or empty required field(s) and the field name. More than 5 requests per second (429) leave no entry in History; only your system receives that response. See Error Handling & Limits.
A required field was missing. SmartSuite returns HTTP 400 to the caller with the name of the missing field, records the run as Rejected and runs no action step. See Required fields.
A field did not come through. Select Details on the run, expand SmartSuite: When webhook is received and then Input to see exactly what arrived. A missing optional field produces an empty output and extra keys are ignored. See Reviewing the Incoming Request in Run History.
The structure changed. Once the automation is enabled, testing is disabled. To map new fields, disable the automation, use Redetermine data structure, then enable it again. See Step 5: Enable & Finalize.
The monthly action limit. Every automation in the workspace started failing at once. The checks are in Fix an automation that did not run.
Still stuck: select the chat button in the lower-right corner of SmartSuite. The panel shows the current service status under Search for help; to reach support, select Ask a question. Include the automation link (the three-dot menu, then Copy Link), the time of the request, the response code your system received and, if the run worked on a record, the link to the record. The full fix guide is Fix an automation that did not run.
Overview
The When a Webhook Is Received trigger provides a dedicated URL for each automation. You can copy this URL and add it to external webhook configurations or your own applications. When SmartSuite receives a valid request at this endpoint, your automation will run.
Key Features
Unique, System-Generated URL: Each trigger has its own webhook endpoint that you can copy and share.
GET & POST Support: Configure your incoming webhook to accept data via URL query parameters (GET) or JSON payloads (POST).
Automatic Field Mapping: SmartSuite can parse JSON bodies or detect query parameters, letting you map them to outputs used in later steps.
Flexible Payload Handling: Requests are accepted on a best-effort basis, a missing field or unexpected value type won't reject the whole request.
Clear Error Handling: Clear, specific messages for requests that can't be processed, with most rejected requests recorded in Run History (requests over the rate limit are not).
Testing & Recent Requests: Check up to 10 recent webhook requests before enabling the automation.
Step 1: Create an Automation
Go to Automations: From the main navigation, select Automations or open the Automation Builder for the desired workspace/solution.
Add Trigger: Click Add New Automation, then choose When a Webhook Is Received as your trigger.
Name & Description: Give your automation a clear name (e.g., “Inbound Webhook for Customer Orders”) and a helpful description.
Tip: Each automation can only have one trigger. If you need multiple webhooks, create multiple automations.
Step 2: Configure Your Webhook
After choosing When a Webhook Is Received:
Copy the Request URL: the Request URL box shows a unique URL generated by SmartSuite. Click Copy to place the URL on your clipboard.
HTTP Method: Select GET or POST, depending on how the external service will send data. The box is empty until you choose a method. Once the automation is on, a request sent with another method is rejected.
Explanation & Testing: Three lines explain the responses. Successful requests will receive a [success: true] response. Requests received while the webhook is off start a new test run. Requests received while it is on run the automation's actions. Below them, the We are listening! box has a Test Trigger button to review inbound requests.
The automation is currently disabled, which allows you to test without running production actions.
Note: Remember that anyone who has the URL for your webhook trigger can trigger your automation. We recommend thinking carefully about how and where this URL might be shared.
Step 3: Test the Webhook
Click Test Trigger to see if any requests have been received:
No Recent Requests: If no requests have been sent to your webhook yet, you’ll see "No Request found yet!" and "Check your application preferences and try again."
Send a Request: From an external system or a tool like Postman/cURL, send a GET or POST request to your webhook URL. (For POST requests with JSON, ensure the
Content-Type: application/jsonheader and valid JSON body.)Refresh & View: Click Refresh to retrieve up to 10 recent requests from the past 24 hours. When requests have arrived, SmartSuite shows We found a request!; choose a request in the list (Request 1 is the newest) to see the data (query parameters for GET or JSON payload for POST).
Note: SmartSuite logs incoming request data for up to 24 hours while the automation is disabled, making it easy to test and configure your field mappings.
Step 4: Map Incoming Data
Once you select a recent request, you can map fields or parameters:
For GET Requests: SmartSuite shows detected query parameters (e.g.,
?order_id=123&status=new). Each parameter is available as a text output. The structure is a list of Query Parameters: each has a name box, a Required checkbox and a delete icon, and + Add Parameter adds one.For POST Requests (JSON): SmartSuite shows the data structure.
Simple Fields (strings, numbers, booleans) appear as
{key}: {value}and become separate outputs in later steps.Arrays are labeled as
{key}: JSON Array, and later steps receive the array as one text value, for example [1,2,3]. Note that arrays at the top (root) level or under the root object can be used in Looping actions.Nested Objects are expanded into dot notation (e.g.,
customer.name,customer.email).
Click Use this structure to confirm SmartSuite should use those fields as outputs in later automation steps. For POST, the Request Content dropdown shows the type of the whole body (JSON Object, JSON Array, Text, Boolean or Number), with the fields below it. A POST webhook cannot be saved until a request has arrived and you select Use this structure. In later steps, select Fields from Trigger: each field appears as Request Data.<key>, nested fields as Request Data.<key>.<subkey>. Request URL, Request Method and Request Raw Body (the body exactly as sent) are listed with them.
Advanced: If you have an array at the top level or just under the root object, you can use it for looping in subsequent steps.
Step 5: Enable & Finalize
Review & Enable: Check your mapped fields. To add a field, select + Select Field and choose its type. Hover a field to edit it (pencil) or delete it (trash); the edit box has Property Name, Field Type (JSON Object, JSON Array, Text, Boolean or Number) and Required (Yes or No). Then switch the automation on with the ON/OFF toggle next to its name, or select Yes, Switch It On when SmartSuite asks.
Go Live: Now, any valid incoming request to the webhook URL will automatically trigger your automation and pass along the mapped data to subsequent steps (e.g., create a record, send a notification, etc.)
Important: Once the automation is enabled, testing is disabled. To test again, switch the automation off and select Redetermine data structure (the circular arrow next to Request Content). While the automation is on, its tooltip says Reconfiguration is disabled while automation is active.
How Flexible Payload Handling Works
The webhook trigger accepts incoming requests on a best-effort basis. Your payload doesn't have to match the configured structure exactly, SmartSuite takes what it can and runs the automation. Nothing needs to be reconfigured, and all existing webhook automations get this behavior automatically.
The examples below assume a webhook configured with four fields: name (Text), age (Number), active (Boolean), and note (Text).
Missing fields don't reject the request
If the payload leaves out a configured field, the request is still accepted and the automation runs. The missing field produces an empty output; every other field still populates:
json
{ "name": "Ada", "age": 36 }
Result: accepted. name = "Ada", age = 36, and note / active come through empty.
Extra fields are ignored
Keys that aren't in your structure are accepted and ignored, no error, and they aren't available for mapping. You can safely delete fields you don't need from the generated structure:
json
{ "name": "Ada", "age": 36, "nickname": "Countess" }
Result: accepted. name and age map as usual; nickname is ignored.
Values pass through as-is
A value whose type doesn't match the configured field type is no longer rejected, it's passed through exactly as sent, with no conversion:
json
{ "name": 42, "age": "thirty" }
Result: name outputs the number 42 (not "42"); age outputs the text "thirty" (not 0, and not an error).
An object or array sent into a single-value field is passed through as a JSON string, so nothing is lost:
json
{ "note": { "text": "hello", "priority": 2 } }
Result: note outputs {"text":"hello","priority":2}.
Note: This describes what the trigger outputs. When a downstream action (Create/Update Record) writes that value into a typed field, the field may still convert or blank it at write time.
Empty values
A key sent as null, or missing entirely, produces an empty value.
A key sent as an empty string (
"") produces an empty string.
When an empty value is mapped into a field by an Update (Replace Value) action, that field is cleared. This applies to every field type, Text, Number, Status, Single/Multiple Select, Linked Record, and Yes/No alike (a Yes/No becomes unchecked).
Required fields
Every field in the webhook structure is optional by default: a missing field produces an empty output and the automation still runs. For POST, hover the field in the structure, select the pencil, set Required to Yes and select Save; the field then shows an asterisk (name*). For GET, tick Required next to the parameter. When a request leaves out a required field, SmartSuite returns HTTP 400 to the caller with the name of the missing field, records the run as Rejected and runs no action steps. Existing webhook automations moved to this behavior automatically; nothing needs reconfiguring.
Note: because a missing optional field is passed on as empty, a later Update Records action set to Replace Value clears the target field. Mark a field Required when that overwrite must not happen.
Error Handling & Limits
Flexible parsing applies to the contents of a valid JSON object. A request is still rejected when:
Wrong HTTP method, the request method doesn't match the method configured on the trigger (
405).Unsupported content type, the body must be sent as
application/json(415).Character encoding, must be UTF-8 (
415).Malformed JSON, a body that isn't parseable JSON (
400).Body isn't a JSON object, for example a bare number or string.
Payload too large, over 1 MB (
413).Rate limit exceeded, more than 5 requests per second (
429).Workspace blocked for billing: every request is answered with 402 (Payment required).
Error messages name the specific problem, for example, the HTTP method actually received versus the one the automation expects, or the content type received.
Requests rejected for the method, the content type, the JSON body or the size appear in History with the Error status and 0 actions; select Details to see why, for example Request is too large. Max size is 1 MB. Requests missing a required field appear with the Rejected status (Rejected without running). No action steps run for either. Requests over the rate limit (429) or for a blocked workspace (402) do not appear in History; only the sending system receives the response.
Reviewing the Incoming Request in Run History
Every run records the incoming request. Open History, select Details on the run, expand SmartSuite: When webhook is received and then Input. It lists Request URL, Request Method, Request Raw Body (the body exactly as sent) and each Request Data value, which helps you spot a field that didn't come through as expected. It is shown for successful runs, runs where an action failed and Rejected runs; a request rejected with Error shows only the reason.
Common Use Cases
3rd Party Integrations: Automate record creation when a third-party service (e.g., payment processor) sends order information.
Custom Applications: Trigger internal business logic in SmartSuite by sending POST requests from in-house tools.
Example of a Zapier workflow that sends to a SmartSuite Webhook Trigger:
Simple Queries: Use GET requests with URL parameters to quickly pass small data (like IDs or statuses) into SmartSuite for immediate processing.
Last verified 29 Oct 2026.