Skip to main content

Validating Received Events

In order to be sure that Toggl is the one sending events to your URL endpoint we include a special HTTP header X-Webhook-Signature-256 that you can use to validate that no one else is sending those requests.

In order to perform this validation you should:

  • Set the field secret while creating a new subscription. If omitted, the system will assign one automatically.
  • When delivering events to your subscription's URL endpoint the system will add the X-Webhook-Signature-256 header.
  • Signature has the form of sha256={value} where value is a HMAC hash based on SHA256 algorithm + secret + body.
  • Example: sha256=6d011bcd0b5bfb7e45372af01bc18f30cc04599df72eca189cdac1094008b095.

Code Examples

In the following examples we will assume that:

  1. We have a subscription where its secret field has the value PGuRrhCFajIyEvFlreKL.
  2. That we received this PING event:
{
"event_id": 0,
"created_at": "2022-06-25T03:58:10.207820267Z",
"creator_id": 6,
"metadata": {
"request_type": "POST",
"event_user_id": 6
},
"payload": "ping",
"subscription_id": 6
}

Which in its raw form is really sent unformatted like this:

{"event_id":0,"created_at":"2022-06-25T03:58:10.207820267Z","creator_id":6,"metadata":{"request_type":"POST","event_user_id":6},"payload":"ping","subscription_id":6}
  1. That we also received the HTTP header x-webhook-signature-256 with the following signature value: sha256=55343383e52a9cd2f56bd4e9fb5b6ce6982fb45955f26ea816cf7495d98c5fd2.

We will then show in different languages how an end user can compute on their side the signature value using the received raw JSON value and the subscription's secret.

message='{"event_id":0,"created_at":"2022-06-25T03:58:10.207820267Z","creator_id":6,"metadata":{"request_type":"POST","event_user_id":6},"payload":"ping","subscription_id":6}'; \
signature=$(echo 'sha256=55343383e52a9cd2f56bd4e9fb5b6ce6982fb45955f26ea816cf7495d98c5fd2' | sed 's/^.*=//'); \
secret=PGuRrhCFajIyEvFlreKL; \
if [[ $signature == $(echo -n $message | openssl dgst -sha256 -hmac $secret | sed 's/^.*= //') ]];
then echo "Valid HMAC";
else echo "Invalid HMAC";
fi
© 2022 Toggl. All rights reserved.