Skip to main content

Validating Events

Overview​

When you configure your server to receive webhook payloads from Splice Exports, it will listen for incoming deliveries at the endpoint you've set up. To ensure security and integrity, it's crucial to validate these webhook deliveries. This verification ensures that the payloads are genuinely from Splice Exports and have not been tampered with during transit. By validating webhook signatures, you can prevent unauthorized access and potential security threats such as man-in-the-middle attacks.

Steps for Validating Webhook Deliveries​

1. Create a Secret Token​

To authenticate incoming webhook deliveries, start by generating a secret token. This token will be used to sign the webhook payloads sent to your server.

  • Create a New Webhook with a Secret Token: When setting up a new webhook in Splice Exports, you'll have the option to create a secret token. This token should be a randomly generated string with high entropy to ensure security.

  • Add a Secret Token to an Existing Webhook: If you already have a webhook set up, you can add a secret token by editing the webhook's settings. Under the "Secret" section, enter your chosen string to use as a secret key.

For detailed steps on creating and managing webhooks in Splice Exports, refer to the Manage Webhooks documentation.

2. Store the Secret Token Securely​

After generating the secret token, it's vital to store it in a secure, accessible location for your server.

  • Do Not Hardcode the Token: Avoid embedding the token directly into your application's code or storing it in any repository. Instead, use secure methods for handling authentication credentials.

  • Use Secure Storage Solutions: Consider storing the token in environment variables or a secure vault.

3. Validate Incoming Webhook Payloads​

When Splice Exports sends a webhook payload, it includes a signature created using your secret token. This signature is found in the X-Signature header of each delivery.

How to Validate the Payload:​

  1. Calculate a Hash: Using the secret token, compute a hash of the incoming payload.
  2. Compare the Hashes: Check the hash you've calculated against the hash sent by Splice Exports in the X-Signature header. Ensure they match to confirm the payload's authenticity.
Important Considerations:​
  • Hashing Algorithm: Splice Exports uses an HMAC hex digest to generate the hash.
  • Signature Prefix: The signature starts with sha256=.
  • Consistent Encoding: Handle the payload as UTF-8, as webhook payloads can contain Unicode characters.
  • Secure Comparison: Use secure comparison methods to prevent timing attacks. Avoid using a simple == operator; instead, use functions like secure_compare or crypto.timingSafeEqual which provide constant time string comparison.

By following these steps, you can ensure that your server processes only legitimate webhook deliveries from Splice Exports, maintaining the security and integrity of your data and systems.