Webhook Signatures

Verify the events that Railz sends to your webhook endpoints.

Railz signs all webhook events it sends to your URL by including a signature in each event’s Railz-Signature header. This allows you to verify that the events were sent by Railz, not by a third party.

Before you can verify signatures, you need to retrieve your webhook URL secret from your Webhooks settings in the Railz Dashboard™. Select a webhook URL that you want to obtain the secret for, then click the Click to Reveal button.

📘

Railz generates a unique secret key for each webhook URL. If you use multiple URLs, you must obtain a secret for each one you want to verify signatures on. Railz will automatically sign each webhook with a signature using its corresponding secret.

Verifying Signatures

The Railz-Signature header included in each signed event contains a timestamp and a signature. The timestamp is prefixed by t=, and the signature is prefixed by v=.

"Railz-Signature": "t=1619201259010,v=878ee5be5b780b0f88d7a7c0c7d4569e78cf3f802acbf3e198944c1bc2b1a6e2"

Railz generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

You can verify the signature by following these steps.

1. Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v corresponds to the signature.

2. Prepare the signed payload string

The signed payload string is created by concatenating:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (i.e., the request body)

3. Generate the expected signature

Generate an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed payload string as the message.

4. Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.