HMAC Signing, Key Rotation, and Webhook Security: What SOC 2 Auditors Actually Ask

SOC 2 does not have a webhook-specific control. It has controls on data in transit, data at rest, access management, and audit logging that all apply to your webhook system. Auditors know this and will ask about webhooks specifically once they understand your product touches them.

Here is what they ask, why they ask it, and the answers that end the conversation quickly.

What are the five questions SOC 2 auditors actually ask?

Not fifty. Five, because these five map to the trust services criteria that touch webhook delivery.

Prepare a one-page answer for each. Auditors move fast when you have documentation ready.

What does HMAC signing look like in practice?

The standard scheme:

1. Compute HMAC-SHA256 of the raw request body using the endpoint's signing secret.
2. Include the signature as a hex or base64 header, typically named something like X-Webhook-Signature.
3. Include a timestamp header (X-Webhook-Timestamp) with unix seconds of the send.
4. Sign the concatenation of timestamp plus body, so the timestamp itself is protected against tampering.

The customer's receiver reverses the process: compute HMAC of received body, compare to the header, verify the timestamp is within a small window (5 minutes is typical) to prevent replay attacks.

Two mistakes that show up in audits.

• Global signing secret. All customers share one secret. If one leaks, everyone is compromised. Per-endpoint secrets contain the blast radius.
• Signing the body only, not the timestamp. Attacker can replay old requests indefinitely. Include timestamp in the signed material.

How do you rotate signing keys without breaking customers?

Dual-key rotation. Never single-cutover.

The mechanism:

1. Customer or you initiate rotation. New secret is generated and returned via API and UI.
2. For 30 days, every outbound request carries two signatures, one with the old secret and one with the new. Both are sent as separate headers.
3. Customer updates their verification to accept the new secret at their convenience during the 30 day window.
4. After 30 days, the old secret is retired and only the new signature is sent.

Auditors want to see three things:

• The rotation is possible without downtime. Documented and demonstrated.
• Rotation events are logged. Who initiated, when, what secret was retired.
• Emergency rotation is possible. If a secret is suspected compromised, the customer can force immediate rotation and accept some receiver downtime.

The dual-key window is the single most important design choice. Anything shorter than 30 days causes customer breakage in a rotation. Anything longer weakens the security value of rotating.

What are the payload encryption requirements?

Two layers, both required for anything touching customer data.

• In transit. TLS 1.3 outbound to customer endpoints. TLS 1.2 is a floor, not a target. Reject connections that cannot negotiate at least 1.2. This is universally expected.
• At rest. Encrypted with per-tenant keys. The database column storing payload bodies is encrypted with a key that lives in a KMS and is unique to the customer's tenant. This means a compromise of the database alone does not expose payloads without also compromising the KMS.

Auditors will ask specifically about key management: who has access to the KMS master keys, how key rotation is handled, how key access is logged. Have answers ready.

For high-sensitivity data (PHI under HIPAA, cardholder data under PCI), add field-level redaction on top: fields marked sensitive are hashed or dropped before storage, so even a full compromise does not surface them.

Who should be able to see webhook payloads and logs?

The default should be almost nobody. Access to payload contents is a common finding when audited.

Recommended access model:

• Customer's team. Can see their own endpoints, attempts, and payloads. Cannot see other customers' data. Scoped by tenant.
• Your DX or support team. Can see attempt metadata (timestamp, endpoint URL, status code, latency) for any customer, for triage. Cannot see payload bodies by default.
• Your engineers. Same as DX for metadata. Payload access requires elevated permission with a justification and audit trail.
• Your SREs during incidents. Payload access via break-glass procedure with automatic audit logging.
• Nobody else. Marketing, sales, and finance have no reason to see delivery data.

Every access to payload contents by non-customer users should be audit-logged. Auditors will ask for a sample of the audit log and check that access is scoped.

What does immutable audit trail actually mean?

An append-only log of every operationally significant action:

• Every replay of an event, with actor, timestamp, and reason.
• Every signing key rotation, with actor, old key id, new key id.
• Every endpoint configuration change, with before-after diff.
• Every access to payload contents by non-customer users.
• Every delivery attempt, with request headers (redacted), response code, and timing.

"Immutable" means the log cannot be edited, only appended. Storage in a WORM (write-once-read-many) system, or in an append-only database table with row-level protection, satisfies this. A regular log file that engineers can sed -i is not immutable.

Retention should match your event retention floor. If you retain events for 30 days, retain the audit log for at least 30 days. Longer is better and cheap.

How do you prove a specific event was sent?

The test auditors will run: "Give me the delivery record for event id evt_abc123 from six weeks ago."

Your answer needs to include:

• The exact timestamp of the send.
• The endpoint URL it was sent to.
• The signature header sent.
• The response code and body received.
• The retry history if any.
• The customer account it belongs to.

Retrievable in under one business day, ideally under one minute if the auditor is watching. If your storage cannot answer this query at all, or requires manual log grep across multiple systems, that is a finding.

What actually matters

The mistake to avoid is treating webhook security as separate from your overall SOC 2 posture. It is not. It is a specific instantiation of the same controls your auditor already knows: signing, key management, encryption, access control, audit trail. Answer each of the five questions in one page, keep the documentation current, and the webhook portion of your audit takes an hour rather than a week. The teams that get slammed on webhook controls in an audit are the ones who never wrote it down, not the ones who did something wrong. Documentation is the deliverable that turns a good implementation into a passing audit.