Webhooks

webhooks are a valid part of the api, enabling developers to utilise data in their applications and connect to third party software tamio uses them to notify a user's application that an event has been triggered on their account there are more than 80 types of events initiated throughout tamio once an event has triggered, we inform your application with real time notifications that include a json payload you can use the data to execute actions in your systems start receiving webhook notifications to receive webhook notifications, you must configure an endpoint url on your account login to your account at tamio com find the developers section and browser to the webhooks tab click the "get started" button on the bottom right enter the url of your endpoint and select which events you would like to receive the url must be https click save the maximum number of endpoints that can be added to a single account is 100 if you require more, please get in touch with our team at api\@tamio com webhook endpoints have a secret key associated with them you can use it to verify that notifications come from tamio and not from third parties webhook signatures & verification tamio webhook events are signed using a hash based message authentication code (hmac) the hmac is calculated using the webhook endpoint's secret key, the payload and a cryptographic hash function sha256 a signature header on an event will have the following structure t=timestamp,s=signature you can verify the signature by making a post request to /v2/webhook endpoints/verify signature using your api key the request must contain the signature as a header and the raw body of the event a 200 response code means the signature has been verified verification failed { "status" 400, "valid" false, "errors" \[ "invalid payload" ] } all webhook signatures contain a timestamp which you can check against a time window that you determine tamio will invalidate any attempts to verify a signature if a timestamp is more than 5 minutes old manual verification to verify a webhook signature manually get the raw body of the request; extract the signature header value from tamio signature create the signed body by concatenating the timestamp the character the request body calculate the hmac using the sha 256 hash function, the secret and the signed body compare the calculated hmac with the one sent in the tamio signature signature header using constant time string comparison check if the timestamp is within your tolerance threshold failures if an event fails to be delivered, tamio has a built in retry mechanism that attempts to resent the event for up to 5 days if this period passes and the event has not been delivered successfully, it will be considered a permanent failure after a permanent failure, if the overall error rate of an endpoint exceeds 75%, it might be disabled do you need a webhook event? let us know at api\@tamio com