Webhook request authentication
For external software systems that provide an endpoint to which webhook requests can be sent, it is important to verify that incoming webhook requests actually originate from ReflexBlue. If this is not possible, anyone who knows the web address (URL) of the endpoint could send webhook requests to it, potentially with malicious payloads and all the associated risks.
To make authentication of webhook requests from ReflexBlue possible for external software systems, ReflexBlue includes a hash-based message authentication code (HMAC) HTTP header with all webhook requests. The HMAC value in this header can be used to verify that the payload in the webhook request is indeed from ReflexBlue.
Calculation of the HMAC value
To calculate the HMAC value of a webhook request, a Secret key is required. When creating an integration in ReflexBlue, a Secret key is automatically generated. You can find this key by opening the integration via the Integrations overview screen.
The Secret key must only be known to ReflexBlue and the external software system. It is therefore important to handle this key with extreme care.
ReflexBlue uses the Secret key to calculate an HMAC value of the payload of the webhook request according to the HMAC-SHA512 algorithm. The calculated HMAC value is sent along with the webhook request as an HTTP header named x-rng-webhook-hmac-sha512 to the external software system.
Upon receiving the webhook request from ReflexBlue, the external software system can use the Secret key to calculate the HMAC value of the payload and compare it to the value sent in the x-rng-webhook-hmac-sha512 HTTP header. If these two values match, the payload is successfully authenticated as originating from ReflexBlue.