Webhook Signature Verification

⚠️ Read Before Using

Webhook Signature Verification — Limited Support Notice

Webhook Signature Verification (WSV) is not fully supported by Hover. It is provided as-is and is not covered by Hover's standard support or reliability commitments. Use at your own risk.

Hover has no visibility into whether you use WSV, or if the signature verification failures occur on your end; if WSV breaks, we will not be alerted and cannot proactively identify the issue.

⚠️ If you choose to use WSV, you must notify Hover before enabling it. ⚠️This allows us to track your integration as a WSV consumer, so that in the event of any future changes we can reach out to you directly before they go live.

To register your integration, contact [email protected]

Overview

Webhook signature verification is a security mechanism used to ensure that data received by a server from a webhook is legitimate and has not been tampered with during transmission. This process involves the webhook provider (Hover) adding a signature to the webhook payload. The receiving server (the service consuming the webhook) then verifies this signature using a shared secret or public key to confirm the authenticity and integrity of the payload.

Please note: Webhook Signature Verification from Hover is not officially supported by our engineering team.

How To Generate a Signature

Saving the HMAC Secret

When you successfully register a webhook with Hover, the response body will includehmac_secret value. This value should be stored as it will be needed to generate the HMAC signature.

This HMAC Secret should be kept private.

//Response Body for a successful POST request to https://hover.to/api/v2/webhooks
{
    "id": 12343,
    "owner_type": "Org",
    "owner_id": 55555,
    "url": "https://yourwebhook.com/hoverwebhook",
    "created_at": "2023-09-11T16:39:01.906Z",
    "updated_at": "2023-09-11T16:39:01.906Z",
    "verified_at": null,
    //store the hmac_secret
    "hmac_secret": "NDYBduht2zrCg6fMXFWadfsT8fT3gQskoFPmRen7KcksDQBqmrpXyx12340ObRqLLjQxBxrTol/lia3WRHtQA==",
    "last_error": null,
    "content_type": "json"
}

Using this hmac_secret value, your integration can recursively generate a signature for all webhook payloads coming from Hover. If the generated signature matches the HMAC signature included in the header of each webhook event, you can verify that the webhook is coming from Hover.

Verifying Hover-Signature-256 (recommended)

Hover signs the raw request body of every webhook and sends the result in two headers:

  • Hover-Signature-256: sha256=<hex> :HMAC-SHA256 (preferred)
  • Hover-Signature: sha1=<hex>: HMAC-SHA1

To verify:

  1. Take the raw request body, exactly as received before any JSON parsing.
  2. Compute an HMAC of the body using your hmac_secret, hex-encoded in lowercase. Use SHA-256 for Hover-Signature-256 or SHA-1 for Hover-Signature
  3. Add the prefix sha256= or sha1= and compare it to the matching header using a constant-time comparison. If they match, the webhook came from Hover.

Legacy: Authorization header

  1. Create a canonical string using the HTTP headers from the incoming webhook, utilizing the Content-Type, Content-MD5, Request URI Path and the DATE timestamp. If content-type or content-MD5 are not present, then a blank string can be used in their place. If the timestamp isn't present, a valid HTTP date is automatically added to the request.
  2. The canonical string is computed as canonical_string = 'content-type,content-MD5,request.path,timestamp'. Here is an example of what this computation could look like:
// these values are for demonstration purposes only and may not reflect actual values

webhook_path = "/webhooks/hover"
incoming_request.content_type = 'application/json'
incoming_request['DATE'] = 'Tue, 06 Aug 2024 23:15:50 GMT'
incoming_request['Content-MD5'] = "QpvEO+siRXYz123n2w3nF6A=="

canonical_string = [
    request.content_type,
    request['Content-MD5'],
    request.path,
  request['DATE']
]

// sample canonical_string output:
//'application/json,w9Yx96Mh3chrdqzbHpI5Wg==,/webhooks/hover,Tue, 10 Mar 2026 16:49:10 GMT'

  1. Use the canonical_string to create the signature, which is a Base64-encoded SHA1 HMAC, using your private hmac_secret key.
    1. Compare it to the Authorization header, which has the format APIAuth <webhook_id>:<signature> .
  2. Confirm that the signature included in the incoming webhook header matches the one you generated. If they match, you can verify the webhook came from Hover.

Sample headers

Here is a sample webhook signature headers Hover sends (we include both SHA-256 and SHA-1 as options):

Hover-Signature: sha1=c01834bbdf48e33f11625a083114634276302f12

Hover-Signature-256: sha256=6dfa2136a84e9541ae370b4e44ef67792c1af313e209c1c85130001392bf0198

Authorization: APIAuth 55555:V/3/SKzzxxULcgZbsF1EEqyiA14=

Webhook Signature Code Example

This code can be used as a template to construct the logic to generate a webhook signature and compare the value with the signature generated by Hover. This is for demonstration purposes only.

require 'net/http'
require 'digest/md5'
require 'base64'
require 'json'
require 'openssl'

# The incoming request. This is based off of a sample request payload that is sent from Hover to your webhook listener.

#your webhook URL
url = "https://frequently-ethical-slug.ngrok-free.app/webhooks/hover"
uri = URI.parse(url)
puts uri
null = nil
incoming_request = Net::HTTP::Post.new(uri)
incoming_request.content_type = 'application/json'
#sample request body sent by Hover that you want to verify
incoming_request.body = '{
  "event": "webhook-verification-code",
  "code": "829924ae-36ba-4190-a013-1f66a276395e", 
  "webhook_id":55555 
}'
#date from the webhook event headers
incoming_request['DATE'] = 'Tue, 06 Aug 2024 23:15:50 GMT'
#Content-MD5 from webhook event headers
incoming_request['Content-MD5'] = "QpvEO+abc123XYz123n2w3nF6A=="
#Authorization header from webhook event headers
incoming_request['Hover-Signature'] = "sha1=c01834bbdf48e33f11625a083114634276302f12"
incoming_request['Hover-Signature-256'] = "sha256=6dfa2136a84e9541ae370b4e44ef67792c1af313e209c1c85130001392bf0198"
incoming_request['Authorization'] = "APIAuth 55555:V/3/SKzzxxULcgZbsF1EEqyiA14="

 # Recommended: Hover-Signature-256 / Hover-Signature, signed over the raw body
def verify_hover_signature(request, hmac_secret)
   sha256_header = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', hmac_secret, request.body)}"
   sha1_header = "sha1=#{OpenSSL::HMAC.hexdigest('SHA1', hmac_secret, request.body)}"
   return request['Hover-Signature-256'] == sha256_header || request['Hover-Signature'] == sha1_header
  end

# Legacy: Authorization header, signed over canonical string 
def authenticate_webhook(request, hmac_id, hmac_secret)
  canonical_string = [
    request.content_type,
    Digest::MD5.base64digest(request.body),
    request.path,
    request['DATE']
  ].join(",")

  puts canonical_string

  sha1_digest = OpenSSL::Digest.new('sha1')
  sha1_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(sha1_digest, hmac_secret, canonical_string))

  return request['Authorization'] == "APIAuth #{hmac_id}:#{sha1_signature}"                                                                             
end

# Use the authentication function

#HMAC secret from the response body from when you initially create the webhook with HOVER 
hmac_secret = "1eQAEqq3knIllqU+/38PBhD62HdAJMZ36+kSabc123456xcyqzMgSrow4mTYhhQ6tQxVJVTgF0NBlWe108ryw=="
#hmac_id == webhook ID
hmac_id = 55555
result = authenticate_webhook(incoming_request, hmac_id, hmac_secret)
puts result

Did this page help you?