Webhooks

Create webhook

To create a webhook:

1. in the Panel, go to Settings and click on the Api Here you can also view if you have API access to integrate with vouchstar
2. Provide Domain
3. Provide Target path
4. Copy the secret key to be used to calculate the digest with the HMAC algorithm

Verify webhook sender

To make sure the webhook is sent by Vouchstar, we sign it with the HMAC algorithm.

To verify the webhook sender:

1. Recieve the webhook body sent by http method POST to domain-target-path set while creating the webhook
2. Request body will be defined as WebhookRequest
3. Generate the digest with the raw WebhookPayload
4. Compare the signature from the WebhookRequest that you received with the generated digest from step 3
5. On successful signature match, you should respond with HTTP response status code 200 OK with body content {"activate": "OK"}

Important

Only this is a successful response:

• HTTP status code 200 OK
• with content

{"activate": "OK"}

!!! Any other response will be treated as an invalid response!

Note

• Do not rely on our IP address for whitelisting them as the webhook sender because they can change.
• Make sure to test your webhooks before setting the production ready Domain and Target path to us.

Generate the signature

To generate the digest, the folowing actions should be applied:

1. Simple parameters should be converted to format: paramter=value eg. currency=USD
2. Objects parameters should be converted to format: objectName.parameter=value eg. user.email=test@email.com
3. Whole list should be converted to lowercase
4. List should be sorted in alpabetical order
5. Sorted parameters should be connected with &
6. Generate the HMAC with the secret key and the prepared signature data from steps 1 - 5 with hash function SHA-512

Formula

signature = signatureAlgorithm(key=value&key1=value1&...&keyN=valueN);

Full example

Signature data:  additional='testing-id' voucher_id='8837104d-3ba7-434d-81c3-0c5f290c1abb' price='20.0' currency='USD' user=SignatureUser(email='example@vouchstar.shop') status='USED' created_at='2024-08-26 11:39:42'
Prepared signature data:  additional=testing-id&created_at=2024-08-26 11:39:42&currency=usd&price=20.0&status=used&user.email=example@vouchstar.shop&voucher_id=8837104d-3ba7-434d-81c3-0c5f290c1abb
Retrieved mac:  vs-sadfhjkhasdjkfbnjaksf7as6f7a8fd78
HMAC SHA-512: 9804a15ec1ef9d2602296237cafde471fdb2990073e34670011e421079b61f582577615e5c937f00cb77379a3543f474e871788376ce30e6487d694e2a8915b0