Skip to main content

​
Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See Getting Started on the Microsoft Dynamics 365 Business Central connector page.

​
How StackOne sets up Business Central webhooks

Nothing needs configuring in Business Central. When you connect an account with events enabled, StackOne lists every company in the connected Business Central environment and creates a webhook subscription for each enabled entity in each company. It deletes them again when the connection is removed.

1

Check the API permission is granted

The subscriptions are created with the Financials.ReadWrite.All permission the connector already uses for every other action. No webhook-specific permission has to be added.

  • If the connection can list companies today, it can create the subscriptions.
2

Check the subscription limit

Business Central allows 200 webhook subscriptions per environment, shared with every other integration on that environment. StackOne creates one subscription per company for each entity that has at least one event enabled.

  • Example: an environment with 2 companies and events enabled for all 22 entities uses 44 subscriptions.
  • If the limit is reached, StackOne can’t create the remaining subscriptions and their events aren’t delivered. In an environment with many companies, enable only the entities you need.
3

Reconnect the account before the subscriptions expire

Business Central expires a subscription three days after it is created, and StackOne does not renew it. Delivery stops silently when a subscription lapses.

  • Reconnect the account, or change its enabled events, to create fresh subscriptions and resume delivery.

​
Available webhook events

Business Central emits created, updated and deleted events for 22 entities in every company of the connected environment. Only events selected in StackOne are delivered. A subscription covers every change to its entity, so enabling any one event of an entity creates that entity’s subscription in each company.

1

Keep the validation check enabled (required)

Business Central verifies the notification URL before it creates each subscription, and refuses the subscription if the check isn’t answered.

  • Validation Check (webhook_validation_check) — Answers Business Central’s validation request when a subscription is created. Must be enabled; without it no subscription can be created and no other event is delivered.
2

Enable the bulk change event

Business Central sends one bulk notification instead of one per record when many records of an entity change at once.

  • Records Changed in Bulk (records_changed_in_bulk) — Fired when more than 1,000 records of one entity change within 30 seconds. It arrives only for entities that have another event enabled.
3

Enable company, employee and setup data events

Events for company information, employees and the setup data shared by documents (countries/regions, currencies, dimensions, payment methods, payment terms and shipment methods).

  • Company Information Updated (company_information_updated) — Fired when a company’s information record is changed
  • Country/Region Created (country_region_created) — Fired when a country/region is created
  • Country/Region Updated (country_region_updated) — Fired when a country/region is changed
  • Country/Region Deleted (country_region_deleted) — Fired when a country/region is deleted
  • Currency Created (currency_created) — Fired when a currency is created
  • Currency Updated (currency_updated) — Fired when a currency is changed
  • Currency Deleted (currency_deleted) — Fired when a currency is deleted
  • Dimension Created (dimension_created) — Fired when a dimension is created
  • Dimension Updated (dimension_updated) — Fired when a dimension is changed
  • Dimension Deleted (dimension_deleted) — Fired when a dimension is deleted
  • Employee Created (employee_created) — Fired when an employee is created
  • Employee Updated (employee_updated) — Fired when an employee is changed
  • Employee Deleted (employee_deleted) — Fired when an employee is deleted
  • Payment Method Created (payment_method_created) — Fired when a payment method is created
  • Payment Method Updated (payment_method_updated) — Fired when a payment method is changed
  • Payment Method Deleted (payment_method_deleted) — Fired when a payment method is deleted
  • Payment Term Created (payment_term_created) — Fired when a payment term is created
  • Payment Term Updated (payment_term_updated) — Fired when a payment term is changed
  • Payment Term Deleted (payment_term_deleted) — Fired when a payment term is deleted
  • Shipment Method Created (shipment_method_created) — Fired when a shipment method is created
  • Shipment Method Updated (shipment_method_updated) — Fired when a shipment method is changed
  • Shipment Method Deleted (shipment_method_deleted) — Fired when a shipment method is deleted
4

Enable finance events

Events for the chart of accounts, posted general ledger entries, general journal batches and customer payment journal batches. Posted ledger entries can’t be changed or deleted, so they only raise a created event.

  • Account Created (account_created) — Fired when an account is created
  • Account Updated (account_updated) — Fired when an account is changed
  • Account Deleted (account_deleted) — Fired when an account is deleted
  • General Ledger Entry Created (general_ledger_entry_created) — Fired when a general ledger entry is created
  • Journal Created (journal_created) — Fired when a journal is created
  • Journal Updated (journal_updated) — Fired when a journal is changed
  • Journal Deleted (journal_deleted) — Fired when a journal is deleted
  • Customer Payment Journal Created (customer_payment_journal_created) — Fired when a customer payment journal is created
  • Customer Payment Journal Updated (customer_payment_journal_updated) — Fired when a customer payment journal is changed
  • Customer Payment Journal Deleted (customer_payment_journal_deleted) — Fired when a customer payment journal is deleted
5

Enable sales events

Events for customers and sales documents (quotes, orders, invoices and credit memos).

  • Customer Created (customer_created) — Fired when a customer is created
  • Customer Updated (customer_updated) — Fired when a customer is changed
  • Customer Deleted (customer_deleted) — Fired when a customer is deleted
  • Sales Quote Created (sales_quote_created) — Fired when a sales quote is created
  • Sales Quote Updated (sales_quote_updated) — Fired when a sales quote is changed
  • Sales Quote Deleted (sales_quote_deleted) — Fired when a sales quote is deleted
  • Sales Order Created (sales_order_created) — Fired when a sales order is created
  • Sales Order Updated (sales_order_updated) — Fired when a sales order is changed
  • Sales Order Deleted (sales_order_deleted) — Fired when a sales order is deleted
  • Sales Invoice Created (sales_invoice_created) — Fired when a sales invoice is created
  • Sales Invoice Updated (sales_invoice_updated) — Fired when a sales invoice is changed
  • Sales Invoice Deleted (sales_invoice_deleted) — Fired when a sales invoice is deleted
  • Sales Credit Memo Created (sales_credit_memo_created) — Fired when a sales credit memo is created
  • Sales Credit Memo Updated (sales_credit_memo_updated) — Fired when a sales credit memo is changed
  • Sales Credit Memo Deleted (sales_credit_memo_deleted) — Fired when a sales credit memo is deleted
6

Enable purchasing events

Events for vendors and purchase invoices.

  • Vendor Created (vendor_created) — Fired when a vendor is created
  • Vendor Updated (vendor_updated) — Fired when a vendor is changed
  • Vendor Deleted (vendor_deleted) — Fired when a vendor is deleted
  • Purchase Invoice Created (purchase_invoice_created) — Fired when a purchase invoice is created
  • Purchase Invoice Updated (purchase_invoice_updated) — Fired when a purchase invoice is changed
  • Purchase Invoice Deleted (purchase_invoice_deleted) — Fired when a purchase invoice is deleted
7

Enable inventory events

Events for items, item categories and units of measure.

  • Item Created (item_created) — Fired when an item is created
  • Item Updated (item_updated) — Fired when an item is changed
  • Item Deleted (item_deleted) — Fired when an item is deleted
  • Item Category Created (item_category_created) — Fired when an item category is created
  • Item Category Updated (item_category_updated) — Fired when an item category is changed
  • Item Category Deleted (item_category_deleted) — Fired when an item category is deleted
  • Unit of Measure Created (unit_of_measure_created) — Fired when a unit of measure is created
  • Unit of Measure Updated (unit_of_measure_updated) — Fired when a unit of measure is changed
  • Unit of Measure Deleted (unit_of_measure_deleted) — Fired when a unit of measure is deleted

​
Delivery format

Details of how Business Central delivers events to StackOne.

1

Retrieve the record to see what changed

A notification identifies the record that changed but doesn’t carry it. The event id is the record’s id, and the notification’s resource names its company and entity in the form api/v2.0/companies({companyId})/{entity}({id}).

  • Read the record with the connector’s matching get action, such as get_customer or get_sales_invoice, using the company id from resource.
  • A deleted record can no longer be read.
  • A change to a line of a sales quote, sales order, sales invoice, sales credit memo or purchase invoice is reported as an updated event on the document itself.
2

Expect a delay of about 30 seconds

Business Central waits 30 seconds after the first change to an entity before it sends notifications, so a record changed several times in that window is reported once for each kind of change (created, updated or deleted) rather than once per change.

  • If more than 1,000 records of one entity change within that window, Business Central sends a single records_changed_in_bulk event instead of one event per record. Its resource carries a $filter on lastDateTimeModified that returns every changed record.
  • Changes made by a delegated admin aren’t sent until a licensed user changes an entity; that notification then includes the delegated admin’s change.
  • Changes made by users who can’t schedule job queues aren’t sent until a user who can makes another change to the same table.
3

Expect batched notifications

Business Central can send notifications from several subscriptions in one request. StackOne splits the batch and delivers each notification as its own event.

4

Expect paired events

Some changes raise more than one event for the same record.

  • Creating a record usually raises both a created event and an updated event for the same id, delivered together.
  • Business Central reports general journal batches and customer payment journal batches on both subscriptions, so a change to either kind raises both a journal event and a customer payment journal event with the same id. get_customer_payment_journal returns 404 when the id belongs to a general journal.
5

Make processing idempotent

Business Central retries a delivery that fails with a timeout, rate limit or server error for up to 36 hours, so the same notification can arrive more than once.

  • Treat each notification as a signal to re-read the record rather than as a change log.
  • Make processing idempotent on the record id so a repeated notification is harmless.

​
Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.