Getting Started
Listen to events in your Beam account on your webhook endpoint so your integration can automatically trigger reactions.
To start receiving webhook events in your app, create and register a webhook endpoint by following the steps below:
- Create a webhook endpoint handler to receive event data POST requests.
- Test your webhook endpoint handler locally.
- 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:
- 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
Updated 5 months ago