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:
- Take the raw request body, exactly as received before any JSON parsing.
- Compute an HMAC of the body using your
hmac_secret, hex-encoded in lowercase. Use SHA-256 forHover-Signature-256or SHA-1 forHover-Signature - Add the prefix
sha256=orsha1=and compare it to the matching header using a constant-time comparison. If they match, the webhook came from Hover.
Legacy: Authorization header
- Create a canonical string using the HTTP headers from the incoming webhook, utilizing the
Content-Type,Content-MD5,Request URI Pathand theDATEtimestamp. Ifcontent-typeorcontent-MD5are 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. - 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'
- Use the
canonical_stringto create the signature, which is a Base64-encoded SHA1 HMAC, using your privatehmac_secretkey.- Compare it to the
Authorizationheader, which has the formatAPIAuth <webhook_id>:<signature>.
- Compare it to the
- 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 resultUpdated 1 day ago

