Webhook callbacks

A callback is the notification that Smartsheet sends to a webhook's callbackUrl. There are two types of callbacks:

• Event Callback: Alerts the subscriber when specified events have occurred. This is the most common type of callback.

• Status Change Callback: Alerts the subscriber that a webhook has been automatically disabled or automatically re-enabled.

As an event subscriber, you can verify callback payload integrity (that is, you can ensure that the message wasn't tampered with enroute) and authenticate the sender identity (that is, you can ensure that the callback originated from Smartsheet). For more information, see Authenticating callbacks.

Notes:

• Smartsheet webhooks don't support callbacks to servers using self-signed certificates. The callback server must use a signed certificate from a certificate authority.
• The callbackURL can't be to a private IP address.
• The callbackURL must use one of the following ports: 443 (default for HTTPS), 8000, 8008, 8080, or 8443.
• If a callback is running for a webhook, that webhook waits on sending sending subsequent callbacks until its current callback finishes.

Event Callbacks

Smartsheet sends an event callback to subscribers when specified events occur.

The callback payload is a skinny payload -- it indicates the changed objects and the event type that occurred in each object, but it doesn't contain any substantial object data.

You can use information and references from the callback's skinny payload and then use the information and references in Smartsheet API requests to retrieve object data associated with the events.

Important: While a webhook is disabled, Smartsheet doesn't send any callbacks for it.

Important: For Smartsheet Commercial, a one-minute debounce optimizes event trigger handling. It reduces traffic and prevents workflows from acting on incomplete or transitional data.

Status Change Callbacks

If a webhook's owner loses access to the object that the webhook monitors (for example, the object was deleted or the webhook owner's access to the object was revoked in Smartsheet), Smartsheet automatically disables the webhook and sends a status change callback to alert the subscriber of the status change. The callback's newWebhookStatus attribute indicates that the webhook is now disabled (because the scope is inaccessible).

If a webhook owner's access to the object is subsequently restored, Smartsheet automatically re-enables the webhook and sends a status change callback to alert the subscriber. The callback's newWebhookStatus attribute indicates that the webhook is now enabled.

Callback acknowledgement

The subscriber must respond to an event callback with a 200 HTTP status code to acknowledge that the callback was received.

Callback delivery retry logic

If the subscriber fails to respond with a 200 status, depending on the response, Smartsheet may retry delivery up to 14 times. (The first seven retry attempts occur with a frequency that's determined using exponential backoff; thereafter, retry attempts occur once every three hours until all retries are exhausted.)

If the response isn't retriable or retry attempts are exhausted, Smartsheet disables the webhook (that is, Smartsheet sets enabled: false and status: "DISABLED_CALLBACK_FAILED").

Note: A disabled webhook that has a status of DISABLED_CALLBACK_FAILED can be re-enabled if the subscriber successfully completes the verification process. For details, see the Webhook verification section in Launch a webhook.

Authenticating callbacks (optional)

As a subscriber you can verify callback payload integrity (that is, you can ensure that the message wasn't tampered with enroute) and and authenticate the sender identity (that is, you can ensure that the callback originated from Smartsheet).

When you create a new webhook, Smartsheet assigns it a randomly generated sharedSecret value. Smartsheet uses the shared secret to sign callback payloads -- don't share the secret with third parties.

Here's how you can authenticate a callback request:

1. Calculate the HMAC of the webhook's sharedSecret and the request body.

Important: You must use the SHA-256 cryptographic hash algorithm.

2. Format the calculated value as a string in base 16.

3. Compare your result with the value of the request's Smartsheet-Hmac-SHA256 header.

If the values match, you the request originated from Smartsheet and that the data hasn't been tampered with.

Note: To improve security, you can reset your webhook's shared secret at periodic intervals.