Merchant Webhooks Authorisation

Actions on how to generate a new webhook or receive the signature. Webhook authorisation is offered for each URL a merchant has registered with Cryptoshack. A signature header contains a timestamp (Unix time in seconds) and a signature, separated by . (dot).

Example

Webhook Header

{
    "signature": "1686025132.f2d04cbc3b1a6dc10a718ccb56d8d071718fc3f226dc0c9f01b60ffe15d34c2b" 
}

JSON payload (request body)

{
    "payload_type": "newCustomer",
    "customer_id": "I6t9GPhFzX",
    "email": "[email protected]",
    "pay_id": "[email protected]",
    "tpa_app_url": "https://cryptovoucher-sandbox.txengine.net/customer/I6t9GPhFzX",
    "message": "Customer was created",
    "ref": ""
}

Signature: 1686025132.f2d04cbc3b1a6dc10a718ccb56d8d071718fc3f226dc0c9f01b60ffe15d34c2b

Unix Time Stamp: 1686025132

Expected Signature: f2d04cbc3b1a6dc10a718ccb56d8d071718fc3f226dc0c9f01b60ffe15d34c2b JSON payload (request body): { "payload_type": "newCustomer", "customer_id": "I6t9GPhFzX", "email": "[email protected]", "pay_id": "[email protected]", "tpa_app_url": "https://cryptovoucher-sandbox.txengine.net/customer/I6t9GPhFzX", "message": "Customer was created", "ref": "" }

Signed_payload: 1686025132.{ "payload_type": "newCustomer", "customer_id": "I6t9GPhFzX", "email": "[email protected]", "pay_id": "[email protected]", "tpa_app_url": "https://cryptovoucher-sandbox.txengine.net/customer/I6t9GPhFzX", "message": "Customer was created", "ref": "" }

Confirming the Signature

1. Split the header, using the . (dot) character as the separator, to get a list of elements.

2. Prepare the signed_payload string, achieved by concatenating:

   • The timestamp from the header (as a string)

   • The character . (dot)

   • The raw JSON payload (request body)

3. Determine the expected signature

   • Compute an HMAC with the SHA256 hash function. Use the URL’s given signature_key (supplied by Cryptoshack) as the key, and use the signed_payload string as the message.

4. Compare signatures

   • Compare the signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

If you need help with coding the signature confirmation, please google 'Compute an HMAC with the SHA256 hash function'.

Example Confirmation

Signature: 1686025132.f2d04cbc3b1a6dc10a718ccb56d8d071718fc3f226dc0c9f01b60ffe15d34c2b

JSON payload (request body): { "payload_type": "newCustomer", "customer_id": "I6t9GPhFzX", "email": "[email protected]", "pay_id": "[email protected]", "tpa_app_url": "https://cryptovoucher-sandbox.txengine.net/customer/I6t9GPhFzX", "message": "Customer was created", "ref": "" }

Key: MERCHANT_API_SIGNATURE_KEY

Step 1: Split the header, using the . (dot) character as the separator, to get a list of elements.

• Unix Time Stamp: 1686025132

• Expected Signature: f2d04cbc3b1a6dc10a718ccb56d8d071718fc3f226dc0c9f01b60ffe15d34c2b

Step 2: Prepare the signed_payload string, achieved by concatenating:

• The timestamp from the header (as a string)

• The character . (dot)

• The raw JSON payload (request body)

• Signed_payload: 1686025132.{ "payload_type": "newCustomer", "customer_id": "I6t9GPhFzX", "email": "[email protected]", "pay_id": "[email protected]", "tpa_app_url": "https://cryptovoucher-sandbox.txengine.net/customer/I6t9GPhFzX", "message": "Customer was created", "ref": "" }

Step 3: Determine the expected signature

• Compute an HMAC with the SHA256 hash function. Use the URL’s given signature_key (supplied by Cryptoshack) as the key, and use the signed_payload string as the message.

• f2d04cbc3b1a6dc10a718ccb56d8d071718fc3f226dc0c9f01b60ffe15d34c2b

Step 4: Compare signatures

• Compare the signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.