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.
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 [email protected]
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.
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.
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.
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.
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 [email protected]