# 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
Lock icon

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

Info icon

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.

Thumbs icon

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.

Updated on: 3/7/2024, 3:05:48 PM