Skip to content
ReferenceForDeveloperHost ownerVendor developer⏱ About 10 min
Before you start:
  • An HTTPS endpoint on your server

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 ​

  1. Read the raw body exactly as received, before any JSON parsing.
  2. Check the signature: v1 must equal the hex HMAC-SHA256 of "<t>.<raw body>" with your endpoint's secret, and t must be within 5 minutes of now. Compare in constant time. Code is on the Host API page in Node, PHP and Python.
  3. Answer 2xx at once. Do the work afterwards (a queue or background job). Slow answers count as failures.
  4. 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.