Smartsheet webhooks
Last verified against Smartsheet's documentation on September 27, 2026.
Smartsheet sends callbacks when something changes on a sheet. Its rules are among the strictest of any webhook provider. It verifies your URL when you enable a webhook and again every 100 callbacks. It requires exactly a 200: a 201 or 204 disables the webhook. It delivers one callback at a time, so a slow response holds up everything behind it. And after 14 failed retries, the webhook is disabled. This page covers what Smartsheet sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Smartsheet sends webhooks for
Callbacks are skinny: they say which objects changed, not what the data is now. Each callback is a JSON POST with the webhookId, the scope and scopeObjectId, a nonce, a timestamp, and an events array. Each event names an objectType (such as sheet, row, cell, or column), an eventType (created, updated, or deleted), and the object’s ID. Use those IDs to fetch the data from Smartsheet’s API.
Smartsheet also sends status change callbacks, with a newWebhookStatus, when a webhook’s owner loses or regains access to the sheet.
How Smartsheet delivers webhooks
| Behavior | Detail |
|---|---|
| Verification | A Smartsheet-Hook-Challenge header on enable, and again every 100 callbacks. Echo it in a Smartsheet-Hook-Response header, or as smartsheetHookResponse in a JSON body |
| Success | Exactly 200 |
| Not retried | 201 to 299, 3xx, and 410. These disable the webhook |
| Retried | Other 4xx, 5xx, and timeouts: up to 14 retries, the first 7 with exponential backoff, then every 3 hours |
| After retries | The webhook is disabled with status DISABLED_CALLBACK_FAILED. Re-enabling means passing verification again |
| Ordering | One callback at a time per webhook. The next waits until the current one finishes |
| Debounce | Events are debounced for one minute |
| Ports | 443, 8000, 8008, 8080, or 8443, with a CA-signed certificate |
Common Smartsheet webhook errors and how to fix them
Webhook disabled after a success
A 201 or 204 isn’t a success to Smartsheet. It disables the webhook. Return exactly 200.
Webhook disabled after working for a while
Smartsheet re-verifies every 100 callbacks. If your handler answers events but not verification requests, the webhook works until the next check, then gets disabled. Handle Smartsheet-Hook-Challenge on every request.
Callbacks arrive slowly
Smartsheet sends one callback at a time. A slow handler delays every callback behind it. Respond first, then process.
Webhook disabled after an outage
After 14 retries, the webhook is disabled with DISABLED_CALLBACK_FAILED. Re-enable it, which runs verification again, then backfill from the API.
Status changes look like events
A callback with newWebhookStatus is a status change, not a data change. Handle it separately.
Why use HookDeploy with Smartsheet
Keep the webhook enabled
HookDeploy captures every Smartsheet webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Smartsheet gets an exact 200 in milliseconds, so slow processing never holds up the callback queue, and an outage on your side can’t disable the webhook.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
- History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
Pass every verification, automatically
Turn on the Smartsheet handshake preset on the endpoint’s Security tab, under Verification (Starter and above). HookDeploy answers the verification when you enable the webhook, and every re-verification after that, even while the endpoint is paused. Verification requests aren’t captured or forwarded.
One webhook, many systems
Send each Smartsheet event to your app, a reporting database, and a team channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems Smartsheet can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so an internal tool or database in a private network can receive Smartsheet events with no public endpoint.
Develop against real events
A tap sends a temporary copy of live Smartsheet events to 127.0.0.1 on your machine while production keeps receiving them.
Know the limits
- Custom responses. Keep the endpoint’s response a
200. A custom response with any other status disables the webhook. - Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Smartsheet treats as a failed delivery. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
HookDeploy forwards Smartsheet’s body and headers unchanged, and callbacks carry only IDs, so a retry or replay is safe to process again: your handler fetches the current data either way.
The handshake preset runs after HookDeploy’s token check, so if your endpoint requires a token, register the callback URL with ?token= added. HookDeploy removes the token before forwarding.
Deduplicate on the callback’s nonce, which is distinct for each callback.
Set up Smartsheet with HookDeploy
- In HookDeploy, create an endpoint (for example,
Smartsheet callbacks) and copy its URL. - On the endpoint’s Security tab, under Verification, choose Smartsheet and save (Starter and above).
- On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- Create the webhook with Smartsheet’s API, using your HookDeploy URL as the
callbackUrl, then enable it. Smartsheet verifies the URL, and HookDeploy answers. - Change the sheet, and confirm the callback appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import express from 'express';
const app = express();
app.post('/webhooks/smartsheet', express.json(), async (req, res) => {
// HookDeploy answers verification requests, so only callbacks reach this handler.
res.status(200).end(); // exactly 200: a 201 or 204 disables the webhook
const callback = req.body;
if (callback.newWebhookStatus) {
await enqueue({ kind: 'status', webhookId: callback.webhookId, status: callback.newWebhookStatus });
return;
}
await enqueue({ kind: 'events', nonce: callback.nonce, sheetId: callback.scopeObjectId, events: callback.events });
// Deduplicate on nonce, then fetch changed rows and cells from Smartsheet's API.
});
FAQ
How does Smartsheet webhook verification work?
When you enable a webhook, Smartsheet sends a Smartsheet-Hook-Challenge header. Your URL must return a 200 and the same value in a Smartsheet-Hook-Response header, or in a smartsheetHookResponse JSON field. Smartsheet repeats this every 100 callbacks.
Why was my Smartsheet webhook disabled?
Either a verification request failed, retries were exhausted, or your endpoint returned a status Smartsheet doesn't retry, such as 201, 204, a redirect, or 410. The webhook's status tells you which: DISABLED_VERIFICATION_FAILED or DISABLED_CALLBACK_FAILED.
Why must a Smartsheet handler return exactly 200?
Smartsheet treats only 200 as acknowledgment. Any other 2xx isn't retried and disables the webhook.
How many times does Smartsheet retry a callback?
Up to 14 times: the first 7 with exponential backoff, then once every 3 hours. After that, the webhook is disabled.
Why don't Smartsheet callbacks include cell values?
Callbacks are skinny by design. They list which objects changed, and you fetch the current data from Smartsheet's API.
Does HookDeploy answer Smartsheet re-verification?
Yes. With the Smartsheet handshake preset on, HookDeploy answers the initial verification and every re-verification, including while the endpoint is paused.