All webhook events BigMailer sends to your endpoints are signed. We do so by including a signature in each event's
X-BigMailer-Signature header. This allows you to verify that the events were sent by BigMailer, not by a third party.
Before you can verify signatures, you need to retrieve your endpoint’s secret from your Webhooks settings. Select an endpoint that you want to obtain the secret for, then click the "show" link.
Each secret is unique to the endpoint to which it corresponds. If you use multiple endpoints, you must obtain a secret for each one.
X-BigMailer-Signature header contains a timestamp and one or more signatures. The timestamp is prefixed by
t=, and each signature is prefixed by a scheme. Schemes start with
v, followed by an integer. Currently, the only valid signature scheme is
X-BigMailer-Signature: t=1492774578, v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8be
Note that newlines have been added in the example above for clarity, but a real
X-BigMailer-Signature header will be all one line.
Split the header, using the
, character as the separator, to get a list of elements. Then split each element, using the
= character as the separator, to get a prefix and value pair.
The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature(s). You can discard all other elements.
You achieve this by concatenating:
- The timestamp (as a string)
- The character
- The actual JSON payload (i.e., the request’s body)
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the
signed_payload string as the message.
Compare the signature(s) in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.
Updated about a year ago