Signatures Guide

Purpose

This guide explains the general process for generating and verifying digital signatures for API requests. It covers the available algorithms and best practices for signing data and verifying authenticity.

Overview of Digital Signatures:

Digital signatures are used to verify that a message or payload has not been tampered with and comes from a trusted source.
They can be applied in various contexts, not just webhooks.

Step 1: Retrieve the Endpoint's Secret Key

You'll find your Secret Key on your Dashboard, in the Webhooks section. Select the endpoint for which you want to get the secret key and click on the "Reveal Secret Key" button.

📘

Multiple Webhook URLs

If you have multiple webhook endpoints, each one will have its own unique Secret Key.

Step 2: Prepare your Signature Base

From signature-input header, take the string following fr1= which will be used to prepare the signature base.

"signature-input": "fr1=("digest");created=1642873384"

// -> ("digest");created=1642873384

Encode the JSON payload of your request with SHA1 (as hex). This is represented as the digest

64d6100989d149061a65e155fb0192fb5799759d

Combine the signature-input and the evaluated digest as in the example below to form your signature base.

"digest": "{evaluted digest}"
@signature-params: {from signature-input}

// The final signature base should look as follows:

"digest": "64d6100989d149061a65e155fb0192fb5799759d"
@signature-params: ("digest");created=1642873384

Step 3: Generate your Signature

To generate the signature value you will need to encode your signature base string from step 2 above.

Compute a HMAC of this string with the SHA256 hash function, using the "Secret Key" retrieved from the Dashboard as the key.

"signature": "75060ab1cee60005cbb316cadbfd235678529f18597ca1a1466abfa3aa1049ae"

Step 4: Compare and Verify Signatures

Compare the signature you have generated to the signature in the header of your webhook (only the value between the 2 : in the signature header). The values should be identical, confirming the webhook is secure and has been sent from Fiat Republic.

Cross-Reference:

For webhook-specific security (including digest verification), please refer to the Webhook Security Documentation Implementation Example.