Create Webhook

POST

https://webhooks.smartsuite.com/smartsuite.webhooks.engine.Webhooks/CreateWebhook

Creates a new webhook with the specified filter criteria. Three levels of filtering are available:

• Solution. Receive events for the entire SmartSuite Solution.
• Application (Table). Receive events for one or more Tables (Apps) in a Solution.
• Application (Table) fields. Limit events to specific fields in a Table (App).

Note

You can currently create any number of webhooks, but be aware that this may be limited in the future.

You must call list payloads at least once every 7 days for the webhook to stay active. After 7 days of inactivity we will disable notifications for your webhook. Webhooks in this state for a further 7 days will be deleted, along with their payloads. Calling list payloads during the 7 day inactive period will re-enable the webhook and extend the timeout period an additional 7 days.

Request Body

Param	Type	Optional	Description
filter	filter object	No	Specifies filters for the returned webhooks.
kinds	array of strings	No	One of the following types of events: RECORD_CREATED RECORD_UPDATED RECORD_DELETED
locator	object	No	Contains workspace and Solution information
webhook_id	string	Yes	leave blank or omit when creating
notification_status	notification_status object	Yes

filter object

Param	Type	Optional	Description
solution	object	Yes*	Pass an empty object to filter at the Solution level
applications	applications filter object	Yes*	Object containing application (table) ids to filter by
application	application fields filter object	Yes*	object containing a list of Table (App) Ids to filter on

Filter: Solution level - no tables/fields

"filter": {
            "solution": {}
          }

Filter: Table (application) level

"filter": {
            "applications": {
                "application_ids": ["some application id"]
            }
          }

Filter: Field level

"filter": {
            "application": {
                "application_id": "some application id",
                "field_ids": [
                    "some field id 1",
                    "some field id 2"
                ]
          }

Note: Filter object

The filter object must contain one (and only one) of the formats listed above. When creating a webhook that monitors changes at the solution level, include the solution filter with an empty object as the request requires the filter object to be populated.

Example Request (Solution filter)

{
    "webhook": {
        "filter": {
            "solution": {}
        },
        "kinds": [
            "RECORD_CREATED"
        ],
        "locator": {
            "account_id": "{{accountId}}",
            "solution_id": "{{solutionId}}"
        },
        "notification_status": {
            "enabled": {
                "url": "https://hook.us1.make.com/pgbpclvi5y9aix2g5cu421paeeq2izzz"
            }
        }
    }
}

Example Request (application (table) filter)

{
    "webhook": {
        "filter": {
            "applications": {
                "application_ids": ["some application id"]
            }
        },
        "kinds": [
            "RECORD_CREATED"
        ],
        "locator": {
            "account_id": "{{accountId}}",
            "solution_id": "{{solutionId}}"
        },
        "webhook_id": "",
        "notification_status": {
            "enabled": {
                "url": "https://sswebhooks.requestcatcher.com/"
            }
        }
    }
}

Example Request (Field filter)

{
    "webhook": {
        "filter": {
            "application": {
                "application_id": "some application id",
                "field_ids": ["some field id 1", "some field id 2"]
            }
        },
        "kinds": [
            "RECORD_CREATED",
            "RECORD_UPDATED"
        ],
        "locator": {
            "account_id": "{{accountId}}",
            "solution_id": "{{solutionId}}"
        },
        "webhook_id": "",
        "notification_status": {
            "enabled": {
                "url": "https://sswebhooks.requestcatcher.com/"
            }
        }
    }
}

Example Request - Solution Filter

curl -X POST https://webhooks.smartsuite.com/smartsuite.webhooks.engine.Webhooks/CreateWebhook \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "ACCOUNT-ID: WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  --data '{
    "webhook": {
        "filter": {
            "solution": {}
        },
        "kinds": [
            "RECORD_CREATED"
        ],
        "locator": {
            "account_id": "{{accountId}}",
            "solution_id": "{{solutionId}}"
        },
        "webhook_id": "",
        "notification_status": {
            "enabled": {
                "url": "https://sswebhooks.requestcatcher.com/"
            }
        }
    }
}'

---

Response

Param	Type	Description
webhook_id	string	Webhook Id
locator	locator object	Contains workspace and Solution information
filter	filter object	Specifies a Solution Id to limit the returned webhooks.
kinds	array of strings	One of the following types of events: RECORD_CREATED RECORD_UPDATED RECORD_DELETED
created_at	created_at object	Created time information
updated_at	updated_at object	Updated time information
notification_status	notification_status object	Webhook notification status
system_status	system_status object	Webhook status

locator object

Param	Type	Description
locator.account_id	object	No
locator.solution_id	object	No
locator.application_id	object	No

created_at object

Param	Type	Description
by	string	Creating user name
at	string	ISO date created

updated_at object

Param	Type	Description
by	string	Updating user name
at	string	ISO date updated

notification_status object

Param	Type	Description
enabled	notification_enabled object	Enables webhook notifications

notification_enabled object

Param	Type	Description
url	string	The webhook notification URL

system_status object

Param	Type	Description
enabled	enabled object	if exists, webhook is enabled
disabled	disabled object	if exists, webhook is disabled

enabled_object object

Param	Type	Description
expires_at	string	ISO date when webhook expires

disabled_object object

| Param | Type | Description | | expires_at | string | ISO date when webhook will be deleted |

Example Response - 200

{
    "webhooks": [
        {
            "webhook_id": "3c8a1835-a39a-43ba-ba9c-6fbce5581e34",
            "locator": {
                "account_id": "WORKSPACE_ID",
                "solution_id": "641b70cb0d94c969a49983aa"
            },
            "filter": {
                "solution": {}
            },
            "kinds": [
                "RECORD_CREATED"
            ],
            "created_at": {
                "by": "Peter Novosel",
                "at": "2023-06-20T14:26:47.192Z"
            },
            "updated_at": {
                "by": "Peter Novosel",
                "at": "2023-06-20T14:26:47.192Z"
            },
            "notification_status": {
                "enabled": {
                    "url": "https://sswebhooks.requestcatcher.com/"
                }
            },
            "system_status": {
                "enabled": {
                    "expires_at": "2023-12-28T19:06:02Z"
                }
            }
        }
    ]
}