Skip to content
HookDeploy
On this page ↓

Handshakes

Answer webhook verification handshakes from Meta, Slack, Zoom, Monday.com, Asana, Smartsheet, Microsoft Graph, Dropbox, and Trello, or define your own, so providers accept your HookDeploy URL.

Some providers won’t send webhooks to a URL until it passes a handshake: they send a challenge, and the URL has to answer it in a specific way. Without the right answer, registration fails. HookDeploy answers these handshakes for you once you turn on the matching preset for an endpoint, so you don’t need a separate server just to register a URL.

Turning a preset on

Open the endpoint’s Security tab, go to Verification, choose a preset, and click Save. Each endpoint has one preset.

Presets are off until you turn them on, on purpose. A handshake is how a provider confirms the URL’s owner wants its events. If HookDeploy answered every handshake on every endpoint, anyone who knew an endpoint’s URL could subscribe it to their own account and send events you never asked for.

Plan availability

Handshake presets are available on Starter and above. On Free, a request that matches a configured preset gets a 403 with a message explaining that verification requires Starter or higher.

Presets

PresetWhat the provider sendsWhat HookDeploy answersNeeds
MetaGET with hub.mode, hub.verify_token, and hub.challengehub.challenge as plain text, if the verify token matchesA verify token
SlackPOST with type: url_verification and a challenge{"challenge": "..."}Nothing
ZoomPOST with event: endpoint.url_validation and a plainTokenThe plainToken and its HMAC-SHA256Your Zoom secret token
Monday.comPOST with a JSON challenge field{"challenge": "..."}Nothing
AsanaPOST with an X-Hook-Secret headerThe same X-Hook-Secret headerNothing
SmartsheetA Smartsheet-Hook-Challenge headerA Smartsheet-Hook-Response header with the same valueNothing
Microsoft GraphPOST with a validationToken query parameterThe decoded token as plain textNothing
DropboxGET with a challenge query parameterThe challenge as plain textNothing
TrelloA HEAD requestAn empty 200Nothing
CustomWhatever you defineWhatever you defineA rule

Meta

Meta covers Facebook, WhatsApp, Instagram, and Messenger. Meta sends a GET request with hub.mode, hub.verify_token, and hub.challenge. HookDeploy checks that hub.verify_token matches the token you configured and returns hub.challenge as plain text.

Setup: choose Meta, enter any string as your verify token, then enter the same string in Meta’s webhook settings.

Slack

Slack sends a POST with {"type":"url_verification","challenge":"..."}. HookDeploy responds with {"challenge":"..."}. There’s nothing else to configure.

Zoom

Zoom sends a POST with {"event":"endpoint.url_validation","payload":{"plainToken":"..."}}. HookDeploy computes an HMAC-SHA256 of the plainToken with your Zoom secret token and responds with both values.

Setup: choose Zoom and enter the secret token from your Zoom app’s event subscription settings. It’s encrypted and never shown in the dashboard again after you save it.

Monday.com

When you create a webhook, Monday.com posts a JSON body with a challenge field. HookDeploy responds with {"challenge":"..."}, the same value.

Asana

When you create a webhook, Asana posts a request with an X-Hook-Secret header while your create request is still waiting. HookDeploy responds with the same X-Hook-Secret header, and Asana finishes creating the webhook.

Asana signs every later event with that secret, in the X-Hook-Signature header. HookDeploy doesn’t store the handshake, so the secret never appears in your request history. Your app gets it from Asana instead: the response to your create webhook call includes it. Store it with the webhook, and your handler can verify every event.

Smartsheet

Smartsheet sends a Smartsheet-Hook-Challenge header when you enable a webhook, and HookDeploy responds with a Smartsheet-Hook-Response header containing the same value.

Smartsheet re-verifies every 100 callbacks and disables the webhook if a re-verification fails. HookDeploy answers every one of them, including while the endpoint is paused.

Microsoft Graph

When you create a Graph subscription, Graph posts to your URL with a validationToken query parameter and expects the decoded token back as plain text within 10 seconds. HookDeploy answers right away.

Graph subscriptions expire and have to be renewed through Graph’s API. HookDeploy answers the validation, but it can’t renew subscriptions for you. Your app still needs to renew them on schedule.

Dropbox

Dropbox verifies a webhook URL with a GET request carrying a challenge query parameter. HookDeploy returns the challenge as plain text, with the X-Content-Type-Options: nosniff header Dropbox asks for.

Trello

Trello sends a HEAD request when you create a webhook and expects a 200. With the Trello preset on, HookDeploy answers every HEAD request to the endpoint with an empty 200 and doesn’t capture it, so these checks don’t fill your request history or reach your destinations.

Custom rules

For providers without a preset, define your own rule. A rule has two parts.

Match:

  • Method: any, GET, or POST.
  • Match on: a query parameter, a header, or a top-level field in a JSON body, by name.

A request matches when the method matches and the named value is present.

Respond with:

  • Plain text body: the value as the whole body, as text/plain.
  • JSON body: {"<key>": "<value>"}, with a key you choose.
  • Response header: a header you name, set to the value, with an empty body.

The editor previews the exact response before you save.

These limits apply to every preset and custom rule:

  • The echoed value can be up to 4 KB.
  • JSON bodies are only checked when they’re 16 KB or smaller.
  • A value echoed into a header can’t contain line breaks or other control characters.
  • Handshake responses are always text/plain or application/json, never HTML, and always include X-Content-Type-Options: nosniff and Cache-Control: no-store.

Handshakes and endpoint security

Monday.com, Asana, Smartsheet, Microsoft Graph, Dropbox, Trello, and custom rules are answered only after the request passes the endpoint’s token and IP checks. If your endpoint requires a token, give the provider your URL with ?token= added. A handshake that fails those checks is blocked like any other request.

Meta, Slack, and Zoom are answered before the token and IP checks. Meta’s verify token and Zoom’s HMAC protect those two.

Every preset still answers while the endpoint is paused, so pausing an endpoint doesn’t cause providers to disable your webhook.

What happens to handshake requests

A handshake that a preset answers is:

  • not stored as a request
  • not counted toward your usage
  • not forwarded to destinations or subscriptions

Handshake history

The Verification panel shows the endpoint’s last 20 handshakes: when each arrived, which preset answered it, and the outcome (answered, rejected, or error) with the status returned. The history never includes the challenge, the response, or any header values.

Suggestions

When a preset is off, a handshake request is captured like any other request. If a captured request looks like a known provider’s handshake, the dashboard suggests the matching preset on the endpoint and in the request inspector. Choosing the suggestion opens the Verification panel with that preset selected, and you still click Save.

When the preset is off

Handshake requests are captured, forwarded, and answered with the endpoint’s normal response, which almost never satisfies the provider, so registration fails. Turn on the preset, then retry the registration in the provider.

Handshakes and custom responses

Your custom response applies to normal webhook traffic. Handshakes a preset answers use the preset’s response instead.

Next steps