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
Overview
The When a Webhook Is Received trigger provides a secure, 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.
Robust Error Handling: Clear, specific messages for requests that can't be processed, with rejected attempts recorded in Run History.
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 Webhook URL: You’ll see a read-only field containing 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.
Explanation & Testing: A brief description is displayed, along with 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 a message like “No requests found yet!”
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. Select a request 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.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}: Array. In this initial release, array items are combined into a single text output. Note that arrays at the top (root) level or under the root object can be used in Looping actions (when available).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.
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. Feel free to add or remove fields manually if needed. Once satisfied, Enable the automation.
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, disable the automation and use the Redetermine data structure button.
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 (Yes/No), 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).
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).
Error messages name the specific problem — for example, the HTTP method actually received versus the one the automation expects, or the content type received.
Rejected requests appear in Run History. A rejected request is recorded as an Error entry in the automation's Run History, so you can see that it arrived and why it was turned away.
Reviewing the Incoming Request in Run History
Every run records the incoming webhook payload. Open the run and expand the When webhook is received trigger step to see exactly what arrived — useful for spotting a field that didn't come through as expected. This is captured for both successful and failed runs.
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.