Checking webhook payloads from a marketing platform

Check a marketing webhook in two stages: authenticate the request with the provider's documented method, then confirm the payload describes an event your integration can use. A valid signature does not make every field complete or relevant, and valid JSON does not establish who sent it.

Identify the subscription and expected event

Record the subscription type, target URL and event that should trigger delivery. HubSpot's current developer-platform configuration separates new CRM object subscriptions from classic event types. Inspect the documentation for the subscription you use before defining a payload contract.

Specify the fields your handler needs, such as an event type and source record reference. Mark each field as required, optional or obtained through a later API lookup. Use an event or delivery reference for duplicate handling if the provider supplies one. Do not assume a webhook contains a complete contact record.

Authenticate and validate

Validate the request against the provider's actual signature version and the request material that version specifies. For HubSpot v3, the documented calculation uses the method, URI, body, timestamp and app secret. The receiver must reject a timestamp older than five minutes and compare the calculated signature with the header.

HubSpot also documents validation of the older v2 signature version for backwards compatibility. Merely finding a signature header is not validation.

After authentication, check that the body parses, the event is supported, required identifiers are present and values have the expected types. Reject or set aside an unexpected shape with a useful error reason. Keep full payloads, especially personal data, out of general-purpose logs when a bounded event reference and field-level error are enough.

HubSpot Webhook Signature Versions

Key Webhook Security & Handling Metrics

Acknowledge what was received

HubSpot describes a 2xx response as acknowledgement of a webhook request. For a handler that processes events later, validate and retain the event before acknowledging it, then perform the downstream update separately. If the event cannot be retained, return an appropriate failure response and check the provider's current retry rules; do not assume every failure response will be retried.

Define how duplicate deliveries are recognised. If events arrive out of order, an older change should not blindly replace newer destination state. Where the payload lacks a value needed for a decision, retrieve the current record through an authorised API and use the webhook as a prompt to recheck it.

Check controlled cases for a valid request, an invalid signature, a missing identifier, an unsupported event and a repeated delivery. Inspect both the handler's recorded outcome and any resulting destination change.