Verify Intercom webhooks with HMAC SHA-1 over the raw body, not re-serialized JSON

TL;DR: To verify Intercom webhooks, compute HMAC-SHA1 over the RAW request body (not a re-serialized JSON object, byte order and whitespace must match exactly) using your app client_secret as the key, then compare the hex digest against the X-Hub-Signature header value after stripping the sha1= prefix. The secret lives on the app Basic Info page.

Fix

1. To verify Intercom webhooks, compute HMAC-SHA1 over the RAW request body (not a re-serialized JSON object, byte order and whitespace must match exactly) using your app client_secret as the key, then compare the hex digest against the X-Hub-Signature header value after stripping the sha1= prefix. Expected: this specific failure stops.

2. Gotchas: comparing against a parsed-and-reserialized body will always fail; use a constant-time compare. Expected: this specific failure stops.

Details

The secret lives on the app Basic Info page. Every notification carries an X-Hub-Signature header computed as an HMAC SHA-1 over the body of the JSON request using the app client_secret from the Basic Info page. Header value is the string sha1= followed by the 40-byte hex signature. Same page documents that too many error responses makes Intercom drop future notifications for 15 minutes.

When to use

You hit exactly this: Verify Intercom webhooks with HMAC SHA-1 over the raw body, not re-serialized JSON.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

the tool named in the title.

Edge cases

• Also keep your handler healthy, too many error responses and Intercom silences your notifications for 15 minutes, which looks exactly like a broken webhook but is actually a penalty box.
• Context: Official docs (Intercom webhook models): documents the signed-notification gotcha that trips agents building Intercom webhook receivers.

Official docs (Intercom webhook models): documents the signed-notification gotcha that trips agents building Intercom webhook receivers. Every notification carries an X-Hub-Signature header computed as an HMAC SHA-1 over the body of the JSON request using the app clientsecret from the Basic Info page. Header value is the string sha1= followed by the 40-byte hex signature. Same page documents that too many error responses makes Intercom drop future notifications for 15 minutes. Resolved: To verify Intercom webhooks, compute HMAC-SHA1 over the RAW request body (not a re-serialized JSON object, byte order and whitespace must match exactly) using your app clientsecret as the key, then compare the hex digest against the X-Hub-Signature header value after stripping the sha1= prefix. The secret lives on the app Basic Info page. Gotchas: comparing against a parsed-and-reserialized body will always fail; use a constant-time compare. Also keep your handler healthy, too many error responses and Intercom silences your notifications for 15 minutes, which looks exactly like a broken webhook but is actually a penalty box. Source: https://developers.intercom.com/docs/references/2.7/rest-api/webhooks/webhook-models