Webhook Signatures

Suggest Edits

Introduction

When you receive events to your webhooks we want you to have full confidence that they not only have come from Fiat Republic, but that the information contained within them has not been tampered with.

We use the draft HTTP Message Signatures standard for our implementation.

All webhook events contains a signature header, which you can re-generate on your side and compare the two signatures to verify that they're identical.

Signatures are comprised of 3 headers:

  1. digest - The JSON payload of your request, encoded with sha1 (as hex).
  2. signature-input - The recipe detailing the values required to generate your signature.
  3. signature - The signature generated by us, to which you will need to compare the signature generated by you.
"digest": "64d6100989d149061a65e155fb0192fb5799759d"
"signature-input": "fr1=("digest");created=1642873384"
"signature": "fr1=:75060ab1cee60005cbb316cadbfd235678529f18597ca1a1466abfa3aa1049ae:"

Verifying your 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.

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.

"signature": "fr1=:75060ab1cee60005cbb316cadbfd235678529f18597ca1a1466abfa3aa1049ae:"

// -> 75060ab1cee60005cbb316cadbfd235678529f18597ca1a1466abfa3aa1049ae

Code Samples

Node.js

/**
 *
 * @param body {string}
 * @param secret {string}
 * @param signatureInput {string}
 */
const makeSignatureNaive = (body, secret, signatureInput) => {
    const digest = crypto.createHash('sha1').update(body).digest('hex');
    const signatureParams = signatureInput.replace("fr1=", "")
    const signatureBase = `"digest": "${digest}"\n@signature-params: ${signatureParams}`;
    const hmac = crypto.createHmac('sha256', secret).update(signatureBase).digest('hex');

    return {
        "Digest": digest,
        "Signature": `fr1=:${hmac}:`,
    }
}

Further examples and test cases: https://gist.github.com/jakub-fiat-republic/5538482e06352993c90f32d195721c60

Updated over 1 year ago