Verify Incoming Webhook Signatures

Verifying webhook signatures is a critical security measure that ensures the webhooks you receive are authentic (they genuinely come from the expected sender) and have not been tampered with during transit (their integrity is intact). This process protects your application from processing malicious or corrupted data.

Webhook signatures are cryptographic hashes generated by the sender using a secret key known only to them and you. The sender includes this signature, typically in a request header. Upon receiving the webhook, your application (or the Hookdeck Event Gateway) can recalculate the signature using the same secret key and the request payload. If the calculated signature matches the one sent in the header, you can trust the webhook's authenticity and integrity.

Hookdeck's Role in Signature Verification

Hookdeck offers flexible ways to handle webhook signature verification, catering to different needs and architectures:

1. Source-Level Verification by Hookdeck: You can configure your Source in Hookdeck to automatically verify the signature of incoming webhooks from the provider (e.g., Stripe, GitHub, Shopify). When Hookdeck successfully verifies the provider's signature (if Source verification is enabled), it adds an x-hookdeck-verified: true header to the request. Independently, as part of its default Destination authentication, Hookdeck signs the Event with its own Hookdeck-specific signature before forwarding it to your Destination . Verifying Hookdeck's signature (and checking for the x-hookdeck-verified: true header if applicable) provides a robust way to ensure webhook authenticity.

2. Verification in Your Application (Using Original Provider's Signature): Alternatively, you can choose to verify the original webhook provider's signature directly within your own application. Hookdeck facilitates this by passing through the original provider's signature headers and the raw request body to your Destination. This approach is useful if Hookdeck doesn't natively support a specific provider's signature scheme, if you have particular compliance requirements to verify the original signature directly, or if you simply prefer to handle this logic in your application.

Verifying Signatures with Hookdeck (Source Verification)

When Hookdeck handles signature verification at the Source , it simplifies your application's security logic.

Configuring Source Signature Verification in Hookdeck

Hookdeck allows you to configure signature verification for your Sources to ensure that incoming webhooks are authentic and have not been tampered with. This involves selecting the appropriate Source Type (e.g., Stripe, GitHub, Shopify, or a generic HMAC/Basic Auth/API Key type) and providing the necessary credentials, such as a signing secret.

This configuration can be managed in several ways:

• Via the Hookdeck Dashboard: You can navigate to your Source settings and configure authentication directly in the UI.
• Via the Hookdeck API: Programmatic configuration is available through our API endpoints for managing Sources.
• Via Terraform: For infrastructure-as-code workflows, you can manage Source authentication settings using the Hookdeck Terraform Provider.

For detailed step-by-step instructions on how to add, edit, or remove source authentication using these methods, please refer to the Sources documentation.

Once configured, Hookdeck will automatically attempt to verify the signature of incoming webhooks for this Source based on the chosen Source Type and provided credentials.

Verifying Hookdeck's Signature at Your Destination

By default, Hookdeck signs all Events it forwards to your Destination using a project-level signing secret. This is part of Hookdeck's Destination authentication. Your Destination should verify this signature to ensure the Event genuinely came from Hookdeck.

1. Obtain Hookdeck Signing Secret: Hookdeck uses a project-level signing secret to generate its signatures. You can find this secret in your Hookdeck dashboard by navigating to Settings > Project > Secrets.

2. Implement Verification Logic: To verify a request allegedly from Hookdeck:

   • Ensure you have access to the raw request body. Many web frameworks require specific middleware to access the raw body before it's parsed (e.g., as JSON).
   • Retrieve the x-hookdeck-signature header from the incoming request. Hookdeck may also send an x-hookdeck-signature-2 header if you are in the process of rolling your signing secret; your verification logic should check against both if present.
   • Compute an HMAC SHA256 hash of the raw request body using your project's Hookdeck signing secret. The resulting hash should be Base64 encoded.
   • Securely compare the computed Base64 encoded hash with the signature(s) provided in the x-hookdeck-signature (and x-hookdeck-signature-2, if applicable) header.

   For the precise algorithm and detailed code examples in multiple languages (Node.js, Python, Go, C#), please refer to the "Hookdeck webhook signature verification" section in our Authentication & Verification documentation.

Verifying Original Provider's Signature in Your Application

In some cases, you might choose to (or need to) verify the original webhook provider's signature directly in your application, even when using Hookdeck. Hookdeck ensures that the necessary original headers and the raw request body are passed to your Destination, enabling your application to perform this verification.

When to Verify the Original Signature in Your Application

• Unsupported Providers: If Hookdeck does not yet offer built-in signature verification for a specific webhook provider. However, get in touch with us to request support for your provider.
• Specific Compliance Needs: Your organization might have security or compliance policies requiring direct verification of the original signature.

Steps for Your Application to Verify the Original Signature

When you decide to verify the original signature in your application, Hookdeck ensures the necessary original request details are passed through. Here’s what your application will typically need to do:

1. Ensure Header Passthrough: Confirm that your Hookdeck Connection is configured to forward all necessary headers from the original provider. This typically includes headers like X-Stripe-Signature, X-Hub-Signature-256 (GitHub), X-Shopify-Hmac-Sha256, etc.
2. Access Raw Request Body: Signature verification almost always requires the raw, unmodified request body. Ensure your application framework provides access to this. Many frameworks parse JSON bodies by default, which can alter the string used for signature calculation.
   • For example, in Express.js, you might use middleware like express.raw({ type: '*/*' }) to get the raw body as a Buffer on req.body, or use a custom middleware (similar to the one shown in the Hookdeck verification example) to populate req.rawBody.
3. Implement Provider-Specific Logic: Each provider has its own method for signature verification. You'll need to:
   • Obtain the provider's signing secret (store this securely, e.g., in environment variables).
   • Follow the provider's documentation to construct the string to be signed.
   • Use the appropriate hashing algorithm (e.g., HMAC-SHA256).
   • Compare your calculated signature with the one received in the header.

To verify signatures from specific API providers (like Stripe, GitHub, Shopify, etc.), always consult their official documentation. Each provider will detail their unique signature scheme, required headers, and often provide libraries or code examples for various programming languages.

Important Considerations

Beyond the basic mechanics of signature verification, several factors are important for a robust webhook handling strategy:

• Timestamp Challenges with Retries: Some webhook providers include a timestamp as part of the signed payload. This helps prevent replay attacks by allowing the verifier to reject signatures that are too old. However, when Hookdeck retries delivering an Event (due to a previous failure at your Destination), the original timestamp is typically preserved if Hookdeck is passing through the original signature. If your verification logic is too strict about timestamp freshness, you might incorrectly reject valid retried Events.

  • Mitigation (if verifying original signature): Allow a wider tolerance for timestamps on retried requests.
  • Benefit of Hookdeck signing: When Hookdeck verifies the original provider's signature at the Source (if configured) and then, as a standard procedure, signs the outbound request to your Destination with its own signature, this can simplify your overall verification strategy. However, be mindful that Hookdeck's own signature does not inherently solve timestamp challenges related to the original provider's signature if you are also verifying that.

• Idempotency Remains Crucial: Signature verification confirms who sent the webhook and that it wasn't tampered with. It does not prevent the same valid Event from being delivered multiple times (e.g., due to network issues, provider retries, or Hookdeck retries). Your application must still be designed with idempotency in mind to ensure that processing the same Event multiple times does not lead to unintended side effects. Use unique Event IDs or other transaction identifiers.

• Preventing Replayed Requests: Signature verification is a primary defense against processing maliciously replayed requests.

  • Timestamp validation: Checking the timestamp in the signature helps ensure the request is recent.
  • Nonce usage: Some providers might include a nonce (a unique, random number). Your system would need to track used nonces.
  • Hookdeck's role: When Hookdeck verifies provider signatures at the Source (if configured), it helps ensure that only legitimately signed Events are processed. Its standard practice of signing outbound requests to your Destination with its own signature mechanism further protects your endpoint by confirming the request came from Hookdeck.

Related Hookdeck Features & Documentation

Source Authentication ->

Learn how Hookdeck verifies webhook signatures at the Source.

Destination Authentication ->

Verify Hookdeck's signature when requests are forwarded to your server.

Sources Documentation ->

Explore the capabilities of Hookdeck Sources.