Webhooks in Business Central

Business Central can push change notifications to external systems via webhook subscriptions, so consumers don't need to poll. It's the recommended way to integrate when external systems need to react to BC changes promptly. The mechanics are simple; the operational discipline is what catches people out.

The model. An external system registers a subscription with BC, declaring:

• The resource to watch — a v2.0 API entity set, e.g. companies({id})/customers or a specific table via a custom API.
• The change types — created, updated, deleted.
• The notification URL — where BC will POST notifications.
• The client state — a token the subscriber chooses, returned in notifications for verification.

BC validates the URL during subscription creation by POSTing a validation token; the URL must return it within seconds, exactly as received. This is how BC verifies the subscriber owns the URL.

Notifications. When a watched resource changes, BC POSTs a notification (or batch of notifications) to the URL. The payload contains resource URLs and change type but not the changed data itself — the subscriber must GET the resource to see what changed.

This indirection is deliberate: it keeps notifications small, lets the subscriber filter by re-checking permissions, and avoids stale data over slow subscribers.

Retry and durability. BC retries failed deliveries for a limited window with exponential backoff. After repeated failures, the subscription is deactivated and the subscriber must re-create it. There is no message replay — if your endpoint is down past the retry window, those notifications are lost. Build for reliability.

Subscription expiry. Subscriptions auto-expire (typically after 3 days). Consumers must renew before expiry by extending the subscription. Renew at half the lifetime to handle clock skew and downtime.

Authentication. Notifications are POSTed as Business Central to the subscriber's URL — no auth header is added by BC. The subscriber authenticates the call by checking that the client state matches the value it gave at subscription time. Treat client state like a shared secret.

Throttling. A tenant has a finite number of active webhook subscriptions and a cap on notification rate. High-change tables (item ledger, GL entry) generate many notifications; subscribe to higher-level entities (sales orders, posted invoices) where possible.

Scale pattern. Don't subscribe directly from a single endpoint to a high-volume entity. Use a webhook → Service Bus or Storage Queue → worker pattern: the webhook handler quickly enqueues the notification and returns 200; a worker processes it asynchronously with retries. This decouples the subscriber's processing time from BC's expectation of a fast 200 response.

When to use. Real-time integration of moderate volume — sync a sales order to a shipping service the moment it's released. For bulk or batch needs, use the API directly with If-Modified-Since or change-tracking semantics.