Business Central API Webhooks: Renewal and Recovery Checklist

A Business Central webhook can be registered successfully while the integration still lacks an answer to a practical question: what happens when the subscription expires, the callback fails, or the receiving worker falls behind?

For AL teams and integration owners, the useful readiness test is wider than seeing a notification arrive. Prove the subscription lifecycle, the receiver's acceptance path, and the business processing result separately. This checklist offers Bitta Apps operating guidance for an API subscriber, not a claim about a customer's integration.

Make renewal an observed operation

Microsoft documents that a subscription is valid for three days unless updated. Renewal uses PATCH and performs a subscriber handshake. The update also requires If-Match; a mismatched ETag prevents the change. See the subscription update reference.

Give renewal an explicit owner and a margin before expiry appropriate to the integration's operating requirements. Record an attempt, its response, and the expiry returned by the service. A timer firing is evidence that renewal was attempted, not that it succeeded.

If the ETag is stale, read the current subscription and reconcile its identity and configuration before deciding how to update it. Avoid turning a failed update into an unexamined second subscription. The intended environment, company, resource, and callback should still match the operating record.

The subscription resource exposes subscriptionId, resource, notificationUrl, and expirationDateTime. Those fields give the team a concrete lifecycle record to inspect. See Microsoft's resource definition.

Keep the handshake path working after deployment

Registration and renewal require the subscriber to return validationToken in the response body with HTTP 200. An optional clientState can accompany notifications as an opaque shared-secret value. Microsoft describes these controls in Working with webhooks.

Test the handshake again after changing the receiver, proxy, routing, or authentication design. A deployment that still serves normal traffic can nevertheless break this specific path. Keep handshake handling distinct from business-notification processing so each has an understandable response contract.

If clientState is part of the design, compare it against the expected subscription secret and keep it out of logs. Store secret references in the support record rather than the secret itself. Decide how invalid input is rejected without treating every callback error as interchangeable.

Separate receipt, acceptance, and business completion

For a hypothetical customer-data synchronization, receipt means the callback arrived. Acceptance means the receiver durably captured the work under its agreed contract. Business completion means the destination reflects the intended customer change or records a meaningful exception.

Define those checkpoints before choosing the response behavior. As professional guidance, acknowledge according to the receiver's actual acceptance contract; do not report successful acceptance after discarding work. Conversely, do not couple the callback to every slow downstream action if a durable processing design is appropriate.

Keep enough correlation information to move from the subscription to the received notification and then to the worker outcome. The evidence should identify the environment, company, resource, and processing result without exposing unnecessary business records or credentials.

Handle a notification as work to evaluate

Notifications are delayed rather than sent immediately. A callback can contain multiple notifications, and a collection change indicates records that should be requested using the supplied resource filter. Microsoft documents these shapes in its notification and change-type guidance.

Inspect every entry in the notification envelope. A receiver written for one item should not silently ignore the rest. Route collection handling to an explicit path rather than pretending it is a single-record update.

Design repeated processing to be safe for the actual destination operation. A read-and-update synchronization and a request that creates an irreversible external effect deserve different handling. The checklist is not a promise of exactly-once delivery; it is a requirement to explain how the application behaves when work is repeated or interrupted.

Map callback failures deliberately

Business Central documents callback retries for HTTP 408, 429, and 5xx responses. Other response codes do not trigger retries and cause the subscription to be deleted. Review the documented subscriber failure behavior before finalizing an error response.

Build a small response matrix for the receiver: valid accepted work, malformed input, unavailable durable storage, and downstream processing failure. For each case, record which response the callback emits, whether work was captured, and what operator action follows.

A callback outage and a worker backlog need different alerts. The first concerns receiving new work; the second concerns completing accepted work. Monitor both alongside renewal success and remaining subscription lifetime.

Keep a reconciliation route outside notification delivery

For the hypothetical customer synchronization, define how the owner compares the permitted source scope with the destination and repairs a gap. Choose the query, checkpoint, and reconciliation window to suit the resource and business requirements. Do not assume notification receipt alone proves that every relevant change reached the destination.

Exercise this path in an isolated test: interrupt the receiver, restore it, inspect the actual subscription state, and verify what the destination contains. Record any required subscription recreation separately from replaying application work. Avoid blindly replaying an operation whose external result is unknown.

Use a compact readiness checklist

• Lifecycle: the intended subscription is present, its configuration is verified, and renewal success updates the observed expiry.
• Handshake: creation and renewal validation work through the deployed receiver path.
• Acceptance: notification input is validated and accepted work is durably identifiable.
• Processing: individual and collection paths produce inspectable destination results.
• Recovery: the team can distinguish missing receipt, processing backlog, and an uncertain external effect, with an owner for each.

If the API itself also needs a design review, our guide to custom API endpoints covers that separate boundary. For help reviewing an AL integration's renewal and recovery design, book a call.