How to Explain a Webhook Signature Verification Failure to a Partner in English

Explaining a webhook signature verification failure to an external partner is a delicate balance: the problem is very likely on their side, but saying so bluntly can sound accusatory, damage the relationship, and make them defensive instead of cooperative. The right English here is specific enough to actually help them fix it, while framed collaboratively enough that it reads as “let’s solve this together” rather than “you broke it.”

Key Vocabulary

Signature verification — the process of confirming that a webhook payload genuinely came from the expected sender and hasn’t been altered, typically by checking a cryptographic signature against a shared secret. “Signature verification is failing on our end for about 12% of your incoming webhooks since yesterday’s deploy.”

Clock skew — a difference between two systems’ clocks large enough to cause time-sensitive checks, like signature timestamps, to fail even though the request is legitimate. “One common cause of this kind of failure is clock skew — if your server’s clock is more than five minutes off from ours, our timestamp check will reject an otherwise valid signature.”

Payload re-serialization — the situation where a JSON payload is parsed and re-encoded before the signature is checked, subtly changing its byte representation (e.g. key order or whitespace) and invalidating the signature. “If the payload is being re-serialized anywhere in your pipeline before the signature check, even a harmless change like key ordering will cause verification to fail.”

Shared secret — the private key both parties use to generate and verify a signature; if either side is using an outdated or mismatched version, verification fails. “Could you confirm which shared secret is currently configured on your end? We rotated ours on the 1st, and this looks consistent with the old secret still being in use.”

Raw request body — the exact, unmodified bytes of the incoming request, which must be used for signature verification rather than a parsed-and-reconstructed version. “Signature verification needs to run against the raw request body before any JSON parsing happens — if your framework parses the body automatically upstream, that’s a common source of this exact issue.”

Describing the Problem Precisely

• “We’re seeing signature verification failures on approximately 12% of webhooks from your integration since July 2nd, and wanted to flag it before it affects more traffic.”
• “Looking at a few failed examples, the timestamps in the payloads are consistently 6-7 minutes ahead of our server time, which points to clock skew as the likely cause.”
• “We compared a failed payload’s raw bytes against what our system received, and the key order differs from a successful one — this often happens when a payload is parsed and re-serialized somewhere before signing.”

Framing It Collaboratively

• “This is a common integration issue and usually has a quick fix — we’re happy to walk through our verification logic together if that would help narrow it down.”
• “Could you check whether your server’s clock is synced via NTP? That would confirm or rule out the clock skew theory quickly.”
• “In the meantime, we haven’t disabled your integration — we wanted to raise this with you first rather than block traffic, since we know 88% of your webhooks are still verifying successfully.”

Professional Tips

• Lead with data, not conclusions. “We’re seeing failures on 12% of webhooks since July 2nd” is neutral and verifiable; “your integration is broken” invites defensiveness before you’ve even suggested a cause.
• Offer the most likely cause as a hypothesis, not an accusation. “This looks consistent with clock skew” leaves room for them to confirm or correct it, rather than asserting fault before you’ve seen their side of the system.
• Mention what’s still working, not just what’s broken. Noting the success rate shows you’re being precise and fair, and reassures the partner that you’re not overstating the severity.
• Offer to collaborate on the fix, especially for anything that touches shared cryptographic logic. Signature verification bugs are often subtle on both ends, and offering to debug together tends to resolve issues faster than a one-way bug report.

Practice Exercise

1. Write a two-sentence, data-led description of a hypothetical webhook failure, including a rough failure rate and a start date.
2. Rewrite the sentence “Your server’s clock is wrong” so it reads as a hypothesis rather than an accusation.
3. Write one sentence offering to collaborate on debugging a shared signature verification issue.

Related Resources

• How to Explain a DNS Propagation Delay in English