Webhook signature verification

In this guide, we’ll cover how to verify webhook signatures from FastPix to ensure that the payloads your application receives are legitimate and have not been altered. Signature verification is a vital security measure that prevents tampering and helps maintain the integrity of your data.

Why should you verify webhook signatures?

Webhook signature verification offers the following benefits:

Security: Protects your application from potential security threats by preventing malicious actors from sending fake or manipulated payloads.
Data integrity: Ensures that the payload remains unaltered and is exactly as FastPix intended.
Trust: Increases the reliability of your FastPix integration by verifying that all data exchanges are valid.

Steps to verify FastPix webhook signatures

Step 1: Retrieve your signing key

The first step is to get your unique webhook signing key from the FastPix dashboard:

Log in to your FastPix account.
Navigate to the "Webhooks" section under the settings or API tab.
Locate your specific webhook and note the "Signing Secret". This is the secret key that FastPix uses to sign the webhook payloads it sends to your application. You will use this key to validate that the payload is genuine.

Step 2. Receiving webhook payloads

When FastPix sends a webhook to your designated endpoint, it includes a signature in the HTTP headers. This signature is used to verify the authenticity of the payload.

The signature is located in the FastPix-Signature HTTP header.
The value of this header is a Base64-encoded HMAC-SHA256 hash of the payload.

Here’s an example of what your endpoint might receive:

POST /your/webhook/endpoint HTTP/1.1
  Host: yourdomain.com
  Content-Type: application/json
  FastPix-Signature: 8Yus0f4y9AMxkkq7x7wiUQmyM+d0shUQLsodxrAE6HU=
  "type": "video.live_stream.created",
  "object": {
  "type": "live"
  "id": "73183ed5e86620908e28a1072f429b8c"
 },
 ...
}

Step 3. Verify the signature

To verify the signature, follow these steps:

Extract the FastPix-Signature header: This is the Base64-encoded HMAC-SHA256 signature sent by FastPix.
Generate the HMAC-SHA256 signature: Use the signing key obtained from the FastPix dashboard to generate an HMAC-SHA256 hash based on the raw webhook payload (the body of the HTTP request). This step ensures that the signature is generated in the same way as FastPix does.
Compare the generated signature with the FastPix-Signature:
- If the generated signature matches the signature from the header, then the webhook is verified.
- If the signatures don’t match, the payload may have been tampered with or the signing key might be incorrect, and you should reject it.

Code snippet for signature generation

Here’s a minimal reference for generating HMAC-SHA256 signatures:

String signingKey = "<your_signing_key>";
String payload = "<your_payload>";
String calculatedSignature = SignatureUtil generateSignature (payload, signingKey);

Parameters to use

When implementing webhook signature verification, you'll need to work with the following parameters:

Payload: This is the raw JSON string of the webhook payload received from FastPix. Ensure that it is used exactly as received, as any alterations can affect the signature verification process.
Provided Signature: This is the signature included in the FastPix-Signature header. It is what you will verify against the signature you generate.
Signing Key: This is the Base64-encoded key retrieved from your FastPix dashboard. You’ll use this key to generate the signature and verify the payload’s authenticity.

Common issues to watch for

Incorrect signing key: Double-check that you’re using the correct signing key from your FastPix dashboard. If you’ve recently rotated your keys, ensure you’re using the updated one.
Base64 encoding: Verify that both the payload and signing key are properly encoded in Base64. Any mistakes in encoding can lead to signature mismatches.
Payload alteration: Ensure that the payload remains unchanged from when it was received. Even minor changes—such as formatting or whitespace—can invalidate the signature.