Webhook verification

When you create a webhook it is disabled by default. To enable the webhook, you must initiate the process that verifies that callbacks are expected at your callback URL. If you endpoint responds successfully, Smartsheet enables your webhook and sends you callbacks as events occur.

The following diagram illustrates webhook verification in the webhook launch process.

When you enable a webhook, Smartsheet sends a verification request to the webhook's callbackUrl to verify that the subscriber expects and can successfully receive callbacks.

The request includes a Smartsheet-Hook-Challenge header that contains a unique random value and includes a request body containing a JSON object with only challenge and webhookId attributes. The challenge attribute is a repeat of the header value for API clients that don't interpret header values.

• To verify the webhook, the subscriber's response to the verification request must return a 200 HTTP status code and must echo back the same unique random value in the Smartsheet-Hook-Response header of the response or with a JSON smartsheetHookResponse attribute. Once Smartsheet receives this verification response, the webhook is enabled (enabled: true and status: "ENABLED").

• If the subscriber does not successfully respond to the verification request, the webhook remains disabled (enabled: false and status: "DISABLED_VERIFICATION_FAILED").

Verification is ongoing

Important: Verification is ONGOING. Once you've enabled a webhook, Smartsheet sends verification requests to its callbackUrl once every 100 callbacks. The subscriber should respond to the verification request as described above -- if the subscriber fails to respond appropriately, Smartsheet disables the webhook (Smartsheet sets enabled: false and status: "DISABLED_VERIFICATION_FAILED").

Making sure callbacks are from your webhook

When a webhook is initially created through the API, the response contains the webhook's ID. If you wish to guarantee that your server only receives callbacks for webhooks that you created, you can check the verification request's webhookID attribute against your list of created webhook IDs. If the ID is not in the list, return a response with a non-200 status code (for example, 403 ForbIDden), and the webhook that initiated the verification request is disabled as described above.