In a HubSpot developer account, navigate to App Settings > Webhooks and configure the target URL and throttling settings for the app
Create subscriptions using POST /webhooks/v3/{appId}/subscriptions specifying eventType (e.g., contact.propertyChange), propertyName for property-change events, and active: true
When a webhook fires, HubSpot sends an X-HubSpot-Signature-v3 header containing an HMAC-SHA256 signature computed over the HTTP method + URL + request body + timestamp
Validate the signature server-side: concatenate the method, URI, raw body, and the X-HubSpot-Request-Timestamp header value, then compute HMAC-SHA256 using the app's client secret as the key
Reject requests where the computed signature does not match the header value or where the timestamp is more than 5 minutes old to prevent replay attacks
Return a 200 response within 5 seconds of receiving the webhook; if processing takes longer, acknowledge immediately and process asynchronously to avoid HubSpot treating it as a failed delivery
Known gotchas
Webhook signature validation uses the raw unmodified request body for the HMAC computation — any middleware that parses or reformats the body before validation will cause signature mismatches
HubSpot retries failed webhook deliveries (non-2xx responses or timeouts) with exponential backoff; idempotency handling on the receiving endpoint is essential to avoid duplicate processing
The X-HubSpot-Signature header (v1) is deprecated in favor of X-HubSpot-Signature-v3 — new integrations should implement v3 validation only
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp