Webhook Signatures

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.

To achieve this, 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 how to create your signature
  3. signature
"digest": "64d6100989d149061a65e155fb0192fb5799759d"
"signature-input": "fr1=("digest");created=1642873384"
"signature": "fr1=:75060ab1cee60005cbb316cadbfd235678529f18597ca1a1466abfa3aa1049ae:"

The signature value is what you'll generate to compare with and validate your webhook events.

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-Input

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

"digest": "64d6100989d149061a65e155fb0192fb5799759d"

Convert the createdAt timestamp of the event from the event payload into seconds, and prefix the digest with the fr1 label, forming your signature-input as seen in the below example.

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

Step 3: Generate your Signature

To generate the signature value you will need to encode your valueToDigest string. It takes form:

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

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

"signature": "75060ab1cee60005cbb316cadbfd235678529f18597ca1a1466abfa3aa1049ae"

Step 4: Compare and Verify Signatures

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


Did this page help you?