Skip to main content

Webhook security and validation

OpenTiendas webhooks include a security mechanism to ensure that the notifications you receive are authentic and originate from your store.

Signature verification​

Each webhook request includes a digital signature generated using HMAC SHA256 and a secret key unique to the webhook. The signature is included in the X-Signature header:

X-Signature: sha256=HASH_GENERATED

The payload (request body) is signed entirely, and you must verify the authenticity of the message by following these steps.

How to validate the signature​

  1. Extract the payload: Retrieve the full JSON body from the incoming request without any modification.
  2. Compute the HMAC SHA256 hash using the secret key associated with the webhook and the extracted body.
  3. Compare the generated hash with the value provided in the X-Signature header.
  4. If the values match, the message is valid and authentic.

Webhook endpoint security best practices​

  • Use HTTPS to secure all communication between OpenTiendas and your webhook endpoint.
  • Validate the X-Signature for every request, including retries, to ensure authenticity.
  • Always respond with a 2xx HTTP status code upon successful receipt to prevent unnecessary retries.
  • Store webhook secrets securely and rotate them periodically if needed.
  • Never expose secrets in client-side code or version control systems.
  • Consider IP whitelisting or additional security measures for sensitive endpoints.
  • Keep webhook handlers fast and reliable by processing events asynchronously where possible.

Code examples​

See complete examples of signature verification in multiple languages in the Sample Code section.

Additional resources​

For detailed information on retries and error handling, see the Retries Guide.