# Enforcing integrity
Every object_payload you receive is accompanied by an object_payload_signature.
This signature (or hash (opens new window)) allows you to make sure that:
- The payload was emitted by Treezor
- The payload has not been altered
Security – Check for integrity
You MUST check the integrity of the payload against the object_payload_signature before trusting it.
# How to check the payload integrity
For each received webhook, follow these steps:
- Flatten the received JSON payload
- Convert UTF-8 characters to their unicode sequence equivalent (
éto\u00e9,èto\u00e8, etc.) - Generate the cryptographic signature of the payload (HMAC using the secret)
- Convert the binary signature to base64
- Compare your signature to the one provided along with the webhook
- Respond according to the comparison result
# Generate your own signature of the payload
To generate the signature, use the webhook_secret as a salt
Information – Convert your signature UTF-8 characters to unicode
Treezor generates the object_payload_signature after converting all UTF-8 characters into the corresponding unicode sequences. You must do the same, otherwise you will produce mismatching signatures. (e.g., é must become \u00e9, è becomes \u00e8).
# Compare your signature with the webhook's signature
# What should my application return?
# Signatures are identical
You should return a 200 HTTP Status Code.
Best practice – Defer the verified webhook in a queeing system for async processing
Without asynchroneous processing, if your code fails to process the webhook, Treezor would not attempt to deliver the webhook again as you have already answered with a 200 HTTP Status Code. This could lead to data inconsistency on your side.
# Signatures don't match
You should return an HTTP Status Code in the 500 range.
Either way, there is no need to populate the response any further.
When your server answers with a Status Code higher than 499 or when it takes more than 150ms to answer, Treezor sends you the webhook again every minute (maximum of 30 attempts). If the 30 attempts limit is reached, then:
- No more attempts are made
- An incident notification is sent to Treezor
Treezor will get in touch with you to diagnose the issue. Once the issue is resolved, webhook are sent normally again.
# Increased security
Treezor offers several ways to increase the security of webhooks:
# IP Restriction
You may request that they be sent to you from a fixed IP. This allows your code to check the source IP in addition to webhooks signatures. To request a fixed IP, please get in touch with your Treezor Account Manager.
By default webhooks are sent from dynamic IP and don't allow for such checks.
# Amazon Web Services SQS
If your infrastructure is built on AWS, you should get in touch with your Treezor Account Manager so that we can setup Amazon SQS instead of relying on webhook signatures.