An HMAC signature is a keyed hash (HMAC-SHA256) of a webhook's timestamp and body, computed with a secret shared with your endpoint, so you can verify that the event came from the gateway and was not altered.
Anyone who learns your webhook URL can send it a request, so a signature is what separates the gateway's events from forgeries. HMAC, defined in RFC 2104, combines a secret key with a hash function, here SHA-256, to produce a code that only holders of the secret can compute. The gateway signs each event with the endpoint's secret; your handler recomputes the code over the same bytes and accepts the event only if the two match. The signature proves origin and integrity. It does not hide the content; that is the job of HTTPS.
Two details make the scheme robust. The signed string includes a timestamp, a separator and the raw body, so a captured request cannot be replayed later: the timestamp is checked against a tolerance, and changing it breaks the signature. And the comparison runs in constant time, so that response timing reveals nothing about how many characters matched.
Example
Suppose an attacker captures a genuine message.failed event and, an hour later, resends it with the status changed to delivered. The altered body no longer matches the signature. Resent unaltered, it carries an hour-old timestamp and fails the tolerance check. Either way the handler rejects it.
Common mistakes
- Verifying a re-serialised body: parsing and re-encoding JSON changes whitespace and key order, so the code never matches. Parse after verifying.
- Using the API key instead of the endpoint's signing secret.
- Comparing with ordinary string equality.
- Rejecting events during a secret rotation; check both secrets until the overlap ends.
At SMSMeteor: X-Meteor-Signature reads t=…,v1=…, where v1 is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the endpoint secret; X-Meteor-Timestamp carries the timestamp in Unix seconds. Five minutes is a sensible tolerance. Secrets are rotated from the panel, with old and new both valid for 24 hours. Replayed events get a new timestamp and signature, and test-key webhooks are signed like live ones. Details are in the webhooks documentation and on the security page.
