Business Central Webhooks: Complete Integration Guide

What is a webhook?

A webhook is a push-style notification mechanism. Instead of repeatedly asking Business Central whether something changed, an external application registers a subscription and provides a notification URL. When a subscribed entity changes, Business Central sends a notification to that URL.

Webhooks are useful for event-driven integrations such as e-commerce, CRM, warehouse, analytics and middleware scenarios.

Polling vs webhooks

With polling, an integration repeatedly calls an API and tries to determine what changed. This can create unnecessary requests and introduces a detection delay.

With a webhook, Business Central pushes a notification when a subscribed entity changes. The external system can then fetch the relevant resource and process the change.

Polling:
External System  ---- GET ---->  Business Central
External System  ---- GET ---->  Business Central
External System  ---- GET ---->  Business Central

Webhook:
External System  ---- Subscribe ---->  Business Central
External System  <--- Notification --- Business Central
External System  ---- GET resource --> Business Central

How Business Central webhooks work

1. Identify an API resource that supports webhooks.
2. Expose a publicly reachable HTTPS notification endpoint.
3. Create a subscription through the Business Central subscriptions API.
4. Business Central sends a validation request containing a validationToken.
5. Return the exact token with HTTP 200 OK.
6. The subscription becomes active.
7. When the subscribed resource changes, Business Central sends a notification.
8. Validate and process the notification, then retrieve current data through the API when needed.
9. Renew the subscription before it expires.

Create a webhook subscription

POST https://api.businesscentral.dynamics.com/v2.0/<environment>/api/v2.0/subscriptions
Content-Type: application/json

{
  "notificationUrl": "https://example.com/api/business-central/webhook",
  "resource": "/api/v2.0/companies(<companyId>)/customers",
  "clientState": "your-verification-value"
}

The exact URL depends on the Business Central environment and API route. The notificationUrl must point to an endpoint your integration controls and can receive HTTPS requests.

The validation handshake

The handshake is mandatory when creating and renewing a webhook subscription. Business Central calls the notification URL with a validationToken query parameter. The subscriber must return that token in the response body with HTTP 200.

POST https://example.com/api/business-central/webhook?validationToken=ABC123

HTTP/1.1 200 OK
Content-Type: text/plain

ABC123

What does a webhook notification contain?

A notification identifies the subscription, the affected resource and the type of change. A simplified example is:

{
  "value": [
    {
      "subscriptionId": "webhook-customers-id",
      "clientState": "your-verification-value",
      "expirationDateTime": "2026-09-15T10:00:00Z",
      "resource": "api/v2.0/companies(<companyId>)/customers(<customerId>)",
      "changeType": "updated",
      "lastModifiedDateTime": "2026-09-13T09:30:00Z"
    }
  ]
}

The changeType can identify changes such as created, updated and deleted. A collection notification can be used when many records are changed and the subscriber should process a filtered collection.

Does the notification contain the complete record?

Think of the webhook as a change notification rather than a complete record payload. The notification provides a resource reference. Your integration can use that reference to call the Business Central API and retrieve the current representation of the entity.

Webhook notification
        |
        v
Identify resource
        |
        v
GET Business Central API
        |
        v
Current entity data
        |
        v
Process / transform / synchronize

Subscription lifecycle

Webhook subscriptions are temporary. Business Central documents a default three-day expiration period when a subscription is not renewed. Store the subscription ID and expirationDateTime and renew before expiry.

PATCH https://api.businesscentral.dynamics.com/v2.0/<environment>/api/v2.0/subscriptions(<subscriptionId>)
Content-Type: application/json

{
  "expirationDateTime": "2026-09-16T10:00:00Z"
}

Renewal also requires the validation handshake. Production integrations should therefore treat subscription renewal as a normal lifecycle operation.

Get and delete subscriptions

GET https://api.businesscentral.dynamics.com/v2.0/<environment>/api/v2.0/subscriptions

DELETE https://api.businesscentral.dynamics.com/v2.0/<environment>/api/v2.0/subscriptions(<subscriptionId>)

Subscription management supports reading, creating, updating and deleting subscription resources.

Custom API pages and webhooks

Custom API pages can also be webhook-enabled when Business Central can send notifications for the exposed entity. For a custom API, the subscription route and resource route use the API publisher, group and version defined by the API page.

api/<publisher>/<group>/<version>/subscriptions

Supported standard resources

Business Central supports webhooks for many standard API entities, including commonly used resources such as:

• Customers
• Items
• Sales orders
• Sales invoices
• Purchase invoices
• Vendors
• Accounts
• Company information
• Employees
• Dimensions
• Currencies

The supported-resource list can evolve, so production solutions should verify the current Microsoft documentation for the exact entity they need.

Notifications are not necessarily immediate

Webhook delivery is designed for change notification, not guaranteed instant delivery for every individual database operation. Business Central can delay notifications to reduce duplicate or excessive messages. Microsoft documents a default delay of about 30 seconds after the first change to an entity.

If many records change within a short period, Business Central can send a collection notification instead of one notification per record. Your integration should therefore handle both individual and collection notifications.

Retry behavior

If Business Central cannot successfully deliver a notification to the subscriber, it can retry for a limited period. Microsoft documents retries for responses such as 408 Request Timeout, 429 Too Many Requests and 5xx errors over the following 36 hours.

This makes it important to design the consumer for duplicate delivery and temporary outages.

ClientState and notification verification

The optional clientState value is included in webhook notifications. It can be used as an opaque value that helps the subscriber verify that a notification belongs to the expected subscription.

Do not treat clientState as a replacement for proper authentication, HTTPS, access control or secure secret management.

Webhook architecture for e-commerce

Business Central
      |
      | Webhook notification
      v
HTTPS Webhook Endpoint
      |
      v
Validation + clientState check
      |
      v
Durable Queue
      |
      v
Integration Worker
      |
      +----> Business Central API
      +----> Shopify / CRM / Warehouse
      +----> Logs + Monitoring

For an e-commerce integration, webhooks can reduce the need for frequent polling. Middleware can receive a change notification, retrieve the latest Business Central resource and synchronize the result with an external platform.

Webhook vs Event Subscriber in AL

These mechanisms solve different integration problems:

• Event Subscriber: Runs custom AL logic in response to events inside Business Central.
• Webhook: Notifies an external system about changes to an API-exposed Business Central entity.

They can also work together. An AL extension can implement business logic and expose custom API resources, while an external integration consumes webhook notifications from those resources.

Webhook vs polling

Polling can be useful for simple prototypes and reconciliation jobs, but frequent polling creates repeated API traffic. Webhooks are better when you want Business Central to notify an external system about supported resource changes.

A robust production architecture can combine both: webhooks provide change detection while a scheduled reconciliation process recovers from outages or missed processing.

Testing a Business Central webhook

1. Use a test Business Central environment.
2. Choose a supported API resource such as customers.
3. Prepare a publicly reachable HTTPS notification endpoint.
4. Create the subscription with Postman or your integration application.
5. Handle the validation token and return HTTP 200.
6. Change a subscribed record in Business Central.
7. Inspect the incoming notification.
8. Use the resource URL to retrieve the current entity.
9. Test renewal before the subscription expires.
10. Test duplicate delivery and temporary endpoint failures.

Common problems

Subscription creation fails

Check the API URL, authentication, resource path, notification URL, permissions and validation handshake.

Validation token is rejected

Make sure the endpoint reads the validationToken query parameter and returns the exact token in the response body with HTTP 200.

No notifications arrive

Check that the subscription exists, the resource is supported, the endpoint is reachable over HTTPS and the subscription has not expired.

Subscription stops after a few days

Check expirationDateTime and implement automatic renewal.

Duplicate processing occurs

Make processing idempotent. Store appropriate processing identifiers or use a reliable queue so retries do not create duplicate business transactions.

Large changes behave differently

Prepare the integration to handle collection notifications rather than assuming every notification represents exactly one record.

Security best practices

• Use HTTPS for the notification endpoint.
• Protect the webhook receiver with appropriate authentication and authorization.
• Validate clientState where appropriate.
• Never expose access tokens, client secrets or sensitive Business Central data in logs.
• Use least-privilege permissions for the integration identity.
• Make processing idempotent so retries are safe.
• Monitor failed deliveries and subscription expiration.
• Use separate configuration and credentials for development, testing and production.
• Validate incoming JSON before processing it.

Recommended production flow

1. Authenticate
      ↓
2. Create subscription
      ↓
3. Complete validation handshake
      ↓
4. Store subscriptionId + expirationDateTime
      ↓
5. Receive notification
      ↓
6. Validate notification
      ↓
7. GET resource from Business Central
      ↓
8. Process business logic
      ↓
9. Record processing result
      ↓
10. Renew subscription before expiry

Frequently asked questions

Do I need AL code to create a webhook subscription?

No. A webhook subscription is managed through the Business Central API. AL is useful when you are building the custom API or business logic behind an integration.

Can I use webhooks with custom API pages?

Yes, custom API pages can be webhook-enabled when they meet Business Central's webhook requirements.

How long does a subscription last?

By default, a subscription expires after three days if it is not renewed.

Does a webhook contain the full customer or order record?

The notification identifies the changed resource. Your integration should use the API resource to retrieve the current entity data when required.

Are webhooks the same as AL Event Subscribers?

No. Event Subscribers are an AL extensibility mechanism inside Business Central, while webhooks notify external systems about changes to API-exposed entities.