Authentication

For every push notification we send, we also send a Cronofy-HMAC-SHA256 header.

This HMAC uses the SHA256 algorithm to hash the body of the push notification using your application’s active client secrets as the encryption key(s). Once this hash is generated it is encoded in base-64 and sent along the push notification in the Cronofy-HMAC-SHA256 header.

As your application’s active client secrets are shared secrets between you and Cronofy, by calculating the HMAC yourself and comparing it to what we sent, you can be sure that the notification has come from Cronofy.

While this will vary based on the language you are working in, the method is the same:

Pass the body of the request and a client secret into a HMAC function, which will output the signature hash.
Check that the signature value exists in the comma-separated list of HMACs passed in the Cronofy-HMAC-SHA256 header. If it does, this proves that both parties knew the same client secret.

We don’t pass any authentication credentials with the notifications. We’ve allowed the callback_url to differ between notification channels (some APIs require it be fixed for all channels) so that you may embed some form of authentication token within the URL if you want an extra layer of security.

Single secret example #

Here’s is an example of a specific client secret and response body, along with the generated HMAC in order to help you verify your implementation.

Client secret #

CRN_NggYusqPGLxwjw5FHOJYOqSrTPNXy8WQf14OID

Request body #

{"example":"well-known"}

Generated header #

Cronofy-HMAC-SHA256: 5DxentQi5YSXODEzTVv06sRwJ3pULIz1KrYv20qxEK0=

Multiple secret example #

Here’s is an example of multiple, specific client secrets and response body, along with the multi-valued HMAC header generated in order to help you verify your implementation.

Your application will generally only be configured with a single secret, and so your verification should pass if any of the received, comma-separated HMAC values matches your generated value.

Client secrets #

CRN_NggYusqPGLxwjw5FHOJYOqSrTPNXy8WQf14OID
CRN_nGlYDFXwfSXgB9rvGNBJyfE454GGPtWIbNuPwr

Request body #

{"example":"well-known"}

Generated header #

Cronofy-HMAC-SHA256: 5DxentQi5YSXODEzTVv06sRwJ3pULIz1KrYv20qxEK0=,BmQmWVuZ70ILWjr1CAt5oC7YOolgnku4WZtlrKfx/6k=