Business Central webhook subscription errors

A Business Central webhook subscription asks the platform to push change notifications to an endpoint you control, instead of your integration polling for changes. Because Business Central never proactively tells a broken subscription's owner that it broke, most failures here show up as notifications simply stopping, not as a visible error.

The subscription validation handshake fails when first creating it

Symptom. Creating a new webhook subscription fails immediately, before any notifications are ever expected.

Cause. Business Central validates a new subscription by sending a validation token to the notificationUrl and requiring the endpoint to echo it back within a short window; if the endpoint isn't reachable, doesn't respond fast enough, or doesn't echo the token exactly as required, the subscription creation itself is rejected.

Fix. Confirm the receiving endpoint is publicly reachable and implements the validation handshake correctly (echoing back the exact validationToken value it receives) before assuming the subscription request itself is malformed.

Prevention. Test the validation handshake in isolation (a simple script that only implements the echo-back behaviour) before wiring the receiving endpoint into the full integration logic, so a handshake bug and a business-logic bug aren't debugged together.

Notifications simply stop arriving after previously working

Symptom. A subscription that was delivering notifications correctly for weeks or months stops, with no error surfaced anywhere in Business Central.

Cause. The most common cause is the subscription's expiration lifetime elapsing without renewal — Business Central does not send a warning before this happens, so an integration that only creates a subscription once and never renews it will eventually go silent with no visible failure.

Fix. Recreate or renew the subscription (checking the subscription's current expiration via the API first) rather than assuming a platform outage — this is by far the most common reason notifications stop with no error.

Prevention. Build subscription renewal into the integration itself as a scheduled task well before the maximum lifetime elapses, rather than treating subscription creation as a one-time setup step.

Notifications arrive but reference records the endpoint can't retrieve

Symptom. A notification is received correctly, but following the resource URL it contains to fetch the actual changed record returns an authorization or not-found error.

Cause. The subscription and the resource-fetch step can authenticate as different identities, or the subscribed resource path and the permissions granted to the consuming application's identity can drift out of sync — particularly after a permission set change on the service account used for the integration.

Fix. Confirm the identity used to fetch the resource named in the notification has read access to that specific resource and company, independent of whatever identity was used to create the subscription itself.

Prevention. Use the same, dedicated service account consistently for both creating the subscription and fetching resources it notifies about, and review that account's permission set whenever the integration's scope changes.

A subscription silently stops covering new records after a company or environment change

Symptom. An established subscription keeps working for existing scope but doesn't notify on records in a company, or scope, added after the subscription was created.

Cause. A webhook subscription's resource path is scoped at creation time (often per-company); adding a new company or expanding integration scope later does not automatically extend an existing subscription to cover it.

Fix. Create an additional subscription explicitly scoped to the new company or resource path rather than assuming an existing subscription's coverage grows with the tenant.

Prevention. Treat "a new company was added" as a checklist item that includes reviewing every existing webhook subscription's scope, not just user licensing and permission sets.

Where to go next

Setting up subscriptions and understanding payload shape in the first place is covered in webhooks in Business Central; the wider API error landscape is in Business Central API errors.