Webhook Authentication

To ensure that the webhook you receive on your endpoint originates from Beam, we provide a mechanism to validate our requests.

It is highly recommended that you validate each webhook you receive using the hash signature of each payload. Beam generates signatures using a hash-based message authentication code (HMAC ) with SHA-256 .

This hash signature is included with the headers of each request as X-Beam-Signature. Please note that the value is base64 encoded.

Webhook Authentication Process

1. Decode the base64-encoded string HMAC key received from Beam Lighthouse. You should receive the bytes value of the key.

2. The JSON request body should be converted into bytes to be signed by the HMAC key. Do note that this process may vary depending on the programming language you are using.

3. The result from 2. when encoded back as a base64 string should match the header X-Beam-Signature.

Example Webhook Data Authentication

You can use the following example data to see if your implementation of the webhook authentication is correct.

• X-Beam-Signature: 1XzWtJHZ9Y1tmjkA/XZUIn1ZHrUQp1d0Ms0oDQfJBto=
• HMAC Key: KOFELguf5L1ltuDlkDHGUkPPnQhrgYYijTR4Fqh7APc=
• Request Body (raw, unformatted):

{"chargeId":"ch_30GtUweMWec7r2hHIsV5xxQeJKp","merchantId":"m_2sHxsByPwESKYM4nMwdEBdhubPS","referenceId":"order#10001","status":"SUCCEEDED","currency":"THB","amount":3000000,"source":"PAYMENT_LINK","sourceId":"57Iot6c11o","transactionTime":"2025-07-23T10:16:12Z","paymentMethod":{"paymentMethodType":"CARD","card":{"last4":"1111","brand":"VISA"},"cardInstallments":null,"cardNetworkToken":null,"qrPromptPay":null,"alipay":null,"weChatPay":null,"trueMoney":null,"linePay":null,"shopeePay":null,"bangkokBankApp":null,"kPlus":null,"scbEasy":null,"krungsriApp":null},"failureCode":"","customer":{"primaryPhone":{"countryCode":"+66","number":"0958051075"},"email":"","deliveryAddress":{"contactName":"","phone":{"countryCode":"","number":""},"address":{"streetAddress":"","city":"","country":"","postCode":""}}},"createdAt":"2025-07-23T10:15:56.102401Z","updatedAt":"2025-07-23T10:16:17.418991Z"}