Getting Started

To start receiving webhook events in your app, create and register a webhook endpoint by following the steps below:

1. Create a webhook endpoint handler to receive event data POST requests.
2. Test your webhook endpoint handler locally.
3. Register your endpoint within Beam using the API.

You can register and create one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

📘

The full list of IP addresses that webhook notifications may come from is:

Sandbox: 34.210.144.21

Production: 35.162.87.245

1. Create a handler

TYPES OF EVENTS

Use the Beam API reference to identify the Event objects your webhook handler needs to process.

Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method. If you’re still developing your endpoint function on your local machine, it can use HTTP. After it’s publicly accessible, your webhook endpoint function must use HTTPS.

Set up your endpoint function so that it:

1. Handles POST requests with a JSON payload consisting of an event object.

2. Register your endpoint in Beam

After testing your webhook endpoint function, register the webhook endpoint’s accessible URL using the API so Beam knows where to deliver events. Registered webhook endpoints must be publicly accessible HTTPS URLs.

Webhook URL format

The URL format to register a webhook endpoint is:

https://<your-website>/<your-webhook-endpoint>

For example, if your domain is https://mycompanysite.com and the route to your webhook endpoint is @app.route('/beam_webhooks', methods=['POST']), specify https://mycompanysite.com/beam_webhooks as the Endpoint URL.

Register a webhook endpoint with the Beam API

Register your webhook endpoint with using the API.

❗️

Handling Webhook Failures

After a number of attempts, if we cannot deliver the event, the registration status will change to SUSPENDED.

Once SUSPENDED, no further attempts will be made to deliver previous or future events to this endpoint. It is VERY important to monitor the statuses of your webhook registrations.

To reactivate your webhook, call the update webhook endpoint. This will update your webhook status to ACTIVE and re-attempt to deliver webhook events that failed to previously send

📘

NOTE: At Least Once Delivery

Beam webhooks guarantee at-least-once delivery. So while rare, it is technically possible to receive the same event twice. Your message handlers should account for that edge case and be idempotent.

3. Secure your endpoint

For a list of IPs that webhook events can originate from our please see Security

Create your authUsername and authPassword

When registering your webhook endpoint, you are required to add a authUsername and authPassword of your choosing.

{
  "authUsername": "bubblegum",
  "authPassword": "hello",
  "callbackUrl": "https://mycompanysite.com/beam_webhooks"
}

Verify Basic Auth with every event

The authUsername and authPassword is encrypted by us and sent with every webhook event. When your receive events to your webhook, you can inspect the header and verify they match by decrypting using the following:

  headers: {
    Authorization: 'Basic c3VBZXJhZWNyZXRVc2VyTmFtZTpzdXBlcnNlY3VyZVBhc3N3b3Jk'
  }

const authorization = request.headers['authorization'];
const auth = Buffer.from(authorization, 'base64').toString("utf8");
const [username, password] = auth?.split(":");

// username = bubblegum, password = hello

❗️

Webhook Header Verification Failure

In the event, the username and password from the request headers in the webhook event do not match what you provided when registering your webhook, we recommend throwing a 401