Webhooks

You can create an HTTPS webhook endpoint to receive events. After you register a webhook endpoint, Beam pushes data when certain events happen in your Beam studio.

Set up your webhook

1. In the Beam application, navigate to the Webhooks page by going to Configuration > Integrations and selecting the "Webhooks" tab.
2. Click "Create Webhook".

Security

Webhooks will often contain sensitive information. URLs could contain query parameters, or headers could contain secrets. For this reason Beam stores these values in an encrypted key vault. They are never stored in plain text.

Configure your handler

Beam will only send webhook requests to an HTTPS endpoint. You will need to set up an HTTPS endpoint that accepts a POST method.

Post body

Beam sends sparse event details to your endpoint. It will send a JSON payload that looks like this:

{
  "studioId": "string",
  "eventType": "string",
  "data": {
    "id": "string"
  }
}

‍

Response

Beam requires a 200 response to be sent in under 30 seconds. If your handler exceeds this, Beam will fail the delivery.

Verifying the event

Without verifying the event, an attacker could send fake data to your endpoint. You should always verify that the webhook came from Beam before acting on them.

Beam sends a Beam-Signature header with every request that you can use to verify request. The header contains a timestamp along with a signed signature. An example header will look like this:

Beam-Signature: t=1792549745244,v1=xxxxxx

The process of verifying the signature is defined in more detail below, but at its most basic you will need to:

1. Re-create the signature using the webhook signing secret and the exact payload used by Beam.
2. Compare the signature sent by Beam with the signature you prepare.

You can either do this yourself, or with the help of some libraries. The Standard Webhooks website has some great tools you can use.

Step 1: Get your webhook signing secret

In the Beam application, navigate to the webhook page. Reveal the "Signing secret" and copy it.

Step 2: Extract the timestamp and the signature from the header

Split the header using the , character. Then split each element on the = character. The t corresponds to the timestamp, and the v1 corresponds to the signature.

Step 3: Prepare the payload to sign

The payload consists of the following:

• The timestamp in milliseconds as a string.
• The character .
• The request body

An example in Node.js might look like:

const payload = `${timestamp}.${req.body}`

‍

Step 4: Create the expected signature

Compute an HMAC with the SHA256 hash function. Use the webhook signing secret retrieved earlier and use the payload as the message.

An example in Node.js might look like:

import { createHmac } from 'crypto'

const createSignature = ({ payload, secret }) => {
  return createHmac('sha256', secret)
  	.update(payload)
  	.digest('hext')
}

‍

Step 5: Compare the signatures

Compare the signature with the signature returned in the header.

You could also check the difference in time between the current timestamp and the one in the header, then decide if the difference is acceptable.

Events

Beam currently sends the following event types:

• asset.created
• asset.edited
• asset.deleted
• ticket.created
• ticket.edited
• ticket.deleted