Appearance
Webhooks
BMA tells your servers when something changes by sending a signed POST to your endpoint. Hosts add endpoints in the host portal (API & webhooks); vendors in the vendor portal (Webhooks). Each endpoint gets only the events picked for it; the full list is in Webhook events.
A delivery
http
POST /bma-events HTTP/1.1
Content-Type: application/json
BMA-Event: entitlement.granted
BMA-Delivery: 8812
BMA-Webhook-Id: 14
BMA-Signature: t=1780326000,v1=5f0c…e9a1
{"id":"evt_…","type":"entitlement.granted","api_version":"2026-11-13","created_at":"2026-06-01T15:00:00Z",
"data":{"external_org_id":"dealer-1042","subscription_id":31,"product":"northwind-desk","product_name":"Northwind Desk",
"plan":"Plus","status":"active","from":"pending","period_end":"2026-07-01"}}Handle it in four steps
- Read the raw body exactly as received, before any JSON parsing.
- Check the signature:
v1must equal the hex HMAC-SHA256 of"<t>.<raw body>"with your endpoint's secret, andtmust be within 5 minutes of now. Compare in constant time. Code is on the Host API page in Node, PHP and Python. - Answer
2xxat once. Do the work afterwards (a queue or background job). Slow answers count as failures. - Dedupe on
id. The same event can arrive twice, or late. Treat events as hints and re-read the truth from the API (for hosts, the entitlements endpoint) when it matters.
Try the check here
Runs in your browser only; nothing is sent. Use a test secret, never a live one.
Retries and switching off
- A failed delivery is retried up to 8 times, waiting longer each time.
- After 25 failures in a row the endpoint is switched off and its owner is emailed. Fix your server, then click Resume in the portal.
- Send test in the portal sends a test event to check your endpoint.
- New secret replaces the signing secret at once (shown once). Update your server straight away.