Secure your webhooks

Use webhook signatures to verify that YumiSign generated a webhook request and that it did not come from a server acting as YumiSign.

Check the webhook signatures

YumiSign can sign the webhook events it sends to your endpoints by including a signature in each event’s YUMISIGN-SIGNATURE header. This allows you to verify that the events were sent by YumiSign, not by a third party.

Before you can verify signatures, you either need to define your own secret key if you are using the webhook on the organization level and the size needs to be equal to 32 characters. If you are using the workflow webhook you have the possibility to define it by yourself. If you have not defined it and you have defined a webhook url, we will generate a secret key for you.

Verifying signatures

The YUMISIGN-SIGNATURE header included in each signed event contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid live signature scheme is v1.

YumiSign generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures).

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (the request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Example

{
   "YUMISIGN-SIGNATURE": "t=1654777927,v1=f881bca6636b73bfd5a424a76a5dae85c3fc7d37f22a47b70d2f16f95063151a"
}