Beam logo

Webhook

Beam uses webhooks to notify your application any time an event happens on your Beam account. One such event that you can be notified about is when a Charge has been transitioned to a successful state.

All of Beam's webhooks will be sent using a HTTP POST request to your registered endpoint. The JSON payload for each request can then be obtained from the request body.

Your Beam webhook integration can be self-managed through your merchant account in Lighthouse under the Developers section.

Webhook Delivery Attempts and Retries

Any 2xx response code we receive from our webhook request are seen as successful so we immediately stop retrying after this.

However, any other response codes such as 4xx or 5xx falls under our failure scenario. By default, Beam attempts to deliver your webhook 10 times with exponential backoff between each interval after which we no longer attempt to make any more requests.

Webhook schemas

We support multiple webhook events to the same URL that you provide for the ease of your integration.

Therefore, we send the type of the event in our header x-beam-event with the value being the event name.

Currently, the following events are supported:

  • charge.succeeded

The schema for each webhook we send is based on the event itself. You can expect the request payload to be the original object as you would expect from calling our GET endpoint on the resource.

For example, when a charge is successful, we trigger a callback to your registered endpoint by sending the header x-beam-event with value charge.succeeded and you can expect the schema payload to be the same as calling a GET /v1/api/charges/{chargeId}.

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.