Subscriptions

Manage the lifecycle of your webhook endpoints. A subscription defines where BMG sends data and which event topics trigger a notification.

All operations use your OAuth Bearer token; your company context is derived from the token.

Create a subscription

POST `/law/api/v1/subscriptions/`

Request Body

Field	Type	Required	Description
`targetUrl`	`string`	Yes	The HTTPS endpoint on your server that will receive deliveries.
`secret`	`string`	Yes	Shared secret (min 8 chars) used to sign every delivery (HMAC-SHA256, see Security).
`events`	`string[]`	Yes	Event names to subscribe to — a parent topic (`["file"]` receives the whole file lifecycle) or a specific child event (`["file.deduction.ready"]` receives only that one). See Events.
`description`	`string`	No	Internal label (max 500 chars).

Delivery settings are platform-managed and returned on read: HTTP method POST, timeout 5000 ms, up to 5 retry attempts.

cURL Request:

curl --request POST \
  --url 'https://sandbox.bmgmoney.com/law/api/v1/subscriptions/' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "targetUrl": "https://api.partner.com/v1/webhooks",
    "secret": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "events": ["file"],
    "description": "File notification webhook"
  }'

Success Response (201 Created):

{ "id": 40 }

One subscription per target URL

A company can have only one active subscription per targetUrl. Creating (or updating to) a URL that another of your subscriptions already uses returns 409 Conflict. To repoint deliveries, update (PUT) or delete the existing subscription instead of creating a new one. Deleted subscriptions free their URL for reuse.

List subscriptions

GET `/law/api/v1/subscriptions/`

curl --url 'https://sandbox.bmgmoney.com/law/api/v1/subscriptions/' \
  --header 'Authorization: Bearer <access_token>'

Success Response (200 OK):

[
  {
    "id": 40,
    "targetUrl": "https://api.partner.com/v1/webhooks",
    "secret": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "method": "POST",
    "timeoutMs": 5000,
    "maxRetries": 5,
    "description": "File notification webhook",
    "events": ["file"],
    "createdAt": "2026-07-20T17:03:34"
  }
]

Other operations

Operation	Endpoint	Notes
Get by id	`GET /law/api/v1/subscriptions/{id}`	Returns the same shape as the list item above.
Update	`PUT /law/api/v1/subscriptions/{id}`	Same body as create. The `events` list is fully replaced — include all desired topics.
Delete	`DELETE /law/api/v1/subscriptions/{id}`	Returns `204 No Content`. Deliveries stop immediately.

Events

Deliveries