Smartsheet webhook verification challenge, then a Sume Format run

To start a Sume Format run from a Smartsheet change, create the webhook, make your endpoint acknowledge Smartsheet's verification challenge, enable the webhook, and then call POST /v1/formats/{handle}/{slug}/runs for each change you care about. The challenge is the step most people miss, and a webhook that never passes it stays disabled.

Smartsheet's page, as read today, does not document HMAC signing or retry behavior, so this post does not claim either.

What Smartsheet documents

The Smartsheet webhooks guide says the endpoint must acknowledge a verification challenge, and that you enable the webhook through the Update webhook operation with enable=true (read 2026-10-10). The page does not describe a signature scheme or a retry policy.

Without a signature, the receiver needs another check, such as an unguessable path and a lookup of the webhook id you registered. Treat an event as a hint to go and read the sheet, not as the data itself.

Read the sheet, then decide

After the event, read the changed rows with your own Smartsheet token and decide which should become runs. This is also where you de-duplicate: a sheet edited five times in a minute should become one run per row, not five.

Put row values in input. input is caller data, at most 64 top-level keys and 2 MiB, and Sume never returns it in output. Asset links in the row must be public HTTPS URLs and fit the attachment budget of 30 files in total.

Batch a whole sheet

A sheet with 60 rows needs one bulk call, not 60. POST .../bulk-runs takes 1 to 100 items with concurrency from 1 to 16, and you poll GET /v1/format-run-queues/{id}. A queue reaching completed only means every item is terminal, so look at counts.failed and requeue those rows. A child that could not start reports format_run_failed_to_start.

Use a queue-level Idempotency-Key built from the sheet id and a revision, so a replayed request returns 202 with the old queue and not a new one.

Write results back

Bulk has no queue webhook, so give each item its own webhook_url, or poll the queue. On each format.run.terminal event, verify the signature, dedupe on request_id, and write the media URL back to the row with a Smartsheet call from your own code. Set generation_spend_cap_usd on every item; the platform maximum is $500 and a sheet is an easy way to multiply a small cost.

Guard an endpoint with no documented signature

Since the Smartsheet page I read does not describe a signature, protect the receiver in other ways. Use a long random path, accept only the webhook id you registered, answer quickly with 200 and do the real work from a queue. Never act on the payload alone; fetch the sheet with your own token and compare it with what you expect.

Keep the Sume key out of the receiver's request logs, and remember the contrast on the return path. Sume's result delivery is signed with HMAC SHA256 over timestamp.raw_body, so verify it even though the inbound side documents less. The weaker link in the chain should not be allowed to spend money without limits, which is why the per-run spend cap matters here.