Webhook Security

To protect the server from unauthorised notifications, we strongly recommend our partners to use Hash-based message authentication code(HMAC) signatures. After HMAC is enabled after the subscription creation, each notification will include a signature calculated using a secret HMAC key and a payload from the notification. By verifying this signature, partner confirms that the notification was sent by Sniptech, and was not modified during transmission.

Generate HMAC signature

To receive HMAC signed notifications, first you generate a secret HMAC key using the POST subscription/{subscriptionId}/secret endpoint for the created subscription.

Picture

Generated Secret Key has to be copied and stored safely in the Partner system (there will be no option to retrieve it later).

Calling the same endpoint again on the same subscription will rotate the key.

Validate HMAC signature

The X-Signature header included in each signed event contains a timestamp and one or more signatures. By default there is no signature until such signature is generated for a subscription by using the endpoint. The timestamp is prefixed by t=, and the signature is prefixed by s. For example:

X-Signature: t=1492774577,s=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Sniptech generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

Step 1: Extract the timestamp and signatures from the header

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 tcorresponds to the timestamp, and s corresponds to the signature.

Step 2: Prepare the signed_payload

The signed_payload string is created by concatenating:

  1. The timestamp (as a string)

  2. The character .

  3. The actual JSON payload (that is, the request body)

Step 3: Determine the expected signature

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.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, 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.

Name: X-Signature

In: header