Outbound Messages
Outbound messages are messages that originate from Business Central to an external system. The messages get triggered by pre-defined business events or background processes.
Outbound Integration Handlers
Outbound integration handlers are created for every outbound message you wish to send to an external system. The integration handler is used to define:
- The outbound event used to trigger the message
- Message Type, EDI Partner, etc.
- The main table that the message is based on
- The payload generation method used to build the outbound payload.
- The API Endpoint
- Additional subscribers (e.g. when you send the same message to multiple partners)
- If you want a delay in the messages. For example, suppose you are posting a large warehouse shipment. In that case, you should delay sending a posted invoice until you are sure everything on the warehouse shipment has been posted to prevent you from sending a message while posting a transaction and later having that transaction rollback.
- Remove Special Characters – Specifies that special characters are removed from the message during HTTP calls when the message is encoded as Base64 text. This is a per-handler override; if Remove Special Characters is already enabled on the API Endpoint, the characters are removed regardless of this setting.
Payload Generation Method
Outbound handlers now support two payload generation methods:
| Method | Purpose |
|---|---|
| Data Exchange Definition | Uses the existing Data Exchange Definition mapping to export the payload from the selected record(s). This is the default option and preserves existing behavior. |
| Custom | Allows a custom payload to be provided or generated outside Data Exchange Definition mappings. |
When Payload Generation Method is set to Data Exchange Definition, the Data Exch. Def. Code must be configured.
When Payload Generation Method is set to Custom, the payload can be supplied in one of two ways:
- Prebuilt payload (for example, uploaded when manually testing with Export Message).
- Subscriber-generated payload via extension event handling by subscribing to
OnGenerateCustomPayloadin codeunit OutboundEventMgt_IH_TSL.
Additional Subscribers continue to reuse the payload generated by the parent handler.
Data Exchange Definitions
The table below specifies the settings to use on Data Exchange definitions for exporting data.
| File Type | Type | Data Handling Codeunit | Reading/Writing Codeunit/XMLport | User Feedback Codeunit |
|---|---|---|---|---|
| XML | Payment Export | 70254543 | 70254543 | 70254544 |
| Json | Payment Export | 70254543 | 70254543 | 70254544 |
Select Integration Hub Export as the Type and the codeunit fields above will be populated automatically based on the File Type you choose. You no longer need to enter these values manually. Selecting this type does not affect any downstream processing — it is only used to apply these defaults.
Outbound Events
You can view a list of available outbound events from the outbound events page. You can also add additional events with an extension.
The following events are more generic:
Synchronise in the background using ModifiedAt date/time (per record)
This outbound event gets triggered by running the Outbound Synchronisation Runner code unit. You can use this event for all tables in Business Central.
The following additional fields are available on the integration handler when using this event:
| Field | Purpose |
|---|---|
| Synch. Wait Time (m/s) | Specifies a delay in milliseconds added after each synchronised message. Use this to avoid hitting external API rate limits when not running in background mode. |
| Run in Background | When enabled, each synchronised record creates its own Job Queue Entry so records can be processed in parallel. Requires a Background Job Category to be specified. |
| Background Job Category | Specifies the Job Queue Category assigned to background synchronisation jobs. All tasks in the same category run sequentially. |
| Background Run Date Formula | Specifies a date formula to delay each message that gets synchronised. Use this to pace the synchronisation and prevent hitting API rate limits. |
Generic record triggered by custom extension (with payload support)
This event is intended to be used by an extension to trigger an outbound message for a specific table. Your extension can fire this event and pass any record to process the outbound message.
Use codeunit OutboundEventHandling_IH_TSL with one of these procedures:
- RunOutboundEventHandlerForAGenericRecordTriggeredByACustomExtension - raises the generic outbound event using normal payload generation.
- GenericRecordTriggeredByCustomExtensionWithPayload - raises the same outbound event with a prebuilt payload.
Warehouse Shipment is created (After warehouse shipment posting)
This outbound event fires after a warehouse shipment is posted (OnAfterPostWhseShipment). Use this event when you need to notify an external system of shipped goods, such as sending an advance shipping notice (ASN).
Additional Subscribers on Outbound Messages
Occasionally, you must send the same message to multiple locations. You can specify this in the Additional Subscribers section on the outbound integration message handler card. When a message is sent as an additional subscriber, it uses the original message that is exported. This approach simplifies the configuration and reduces the amount of reads to handle this.
Reducing Noise: Only Send What Matters
To streamline outbound communications and reduce unnecessary system traffic, the Field Value Snapshot feature ensures messages are only triggered when meaningful data changes occur.
Standard Mode (default)
Every update to a record will trigger a message (irrespective of which fields get changed)
Snapshot Mode (Configured Fields Only)
- You define which fields are important for integration.
- The system tracks and stores the last known values of these fields.
- When a record is updated, it checks whether any of the tracked fields have changed.
- A message is sent only if a relevant field has changed.
- After sending, the system updates its stored values.
How to Enable Snapshot Mode
- Open the Outbound Integration Message Handler.
- Turn on Snapshot Data Check Mode.
- Go to Configure Snapshot Fields:
- Select the fields that should trigger outbound messages when changed.
- Once enabled, the system will only publish messages when those specific fields are updated—helping reduce noise and improve integration relevance.
Snapshot Mode is ideal for high-volume records where only certain changes matter. It helps reduce message clutter, improves system performance, and ensures downstream systems receive only the updates that matter.
Snapshot values are stored as text in the background. If a field contains more than 250 characters, it will not be tracked for changes. Instead, the system will always assume it has changed.
Direct Calls to Endpoints
By default, Integration Hub wraps outbound messages in a JSON payload when communicating via Azure API Management (APIM). If you are integrating directly with a REST API — without APIM in between — you can use Direct Call mode to send the Data Exchange output as the raw HTTP body instead.
The following fields are available on the Outbound Integration Handler:
| Field | Purpose |
|---|---|
| Use Direct Call | When enabled, the integration handler sends the Data Exchange output directly to the API endpoint as the HTTP body, bypassing the standard JSON envelope. Do not use this with APIM. |
| Direct Call Content Type | Specifies the HTTP Content-Type header for the direct call. Defaults to application/json. |
Handling Responses from Outbound HTTP Calls
When making direct HTTP calls to external endpoints, Integration Hub can process the response body returned by the endpoint as an inbound message. Enable the Handle Return Message field on the Outbound Integration Handler, and configure a corresponding Inbound Integration Handler to handle the response.
This is useful when an external API returns a result that needs to be processed — for example, receiving a confirmation ID or a status payload immediately after posting.
Handle Return Message is not compatible with the Skip Error on Failed Call option on the API Endpoint.
Update Values after Export
If you want to update a record immediately after it has been sent, you can specify values to be updated on the integration handler on the After Export Tab. You can optionally choose to run the modify trigger.
When you run the trigger, there is a possibility for recursion if you do not have filters that exclude this. The program will error if it detects recursion.
Outbound Job Queue Processing
The app supports delayed messages and synchronisation of records in the background. The messages processed in the background will create Queued Integration Messages. The following job queue entries are available to process these queued messages.
| Object | Purpose | Parameter String |
|---|---|---|
Codeunit ProcessOutIntJQEntry_IH_TSL | This job will process delayed outbound messages. Delayed messages get created when you specify a delay on the integration handler. | You can leave this empty or provide a filter on the integration handler code. |
Codeunit OutIntSyncRunner_IH_TSL | This job will process the outbound synchronisation for handlers that are configured to synchronise using the last modified at date. | You can leave this empty or provide a filter on the integration handler code. |
The app assists you in configuring the job queue as soon you specify that you want to delay a message or if you select an outbound event that requires you to configure a job queue. The app also checks when you open the Outbound Integration Handlers page or the Queued Integration Messages page.
Testing Outbound Integration Handlers
Choose "Export Message". The following applies:
- A filter page opens where you can specify filters for the record.
- You will receive a confirmation message if multiple records exist within the filters specified, and you can choose to cancel or continue
- Each record (within the filters specified) is then published using the integration handler.
When Payload Generation Method is Custom, an additional prompt appears after you choose the record filter:
- Provide payload now
- Run without payload (raise subscriber event)
If you choose Provide payload now:
- You are prompted to upload a payload file.
- The selected filter must resolve to a single record.
If you choose Run without payload (raise subscriber event):
- The system runs the standard publish flow for each record in the selected filter.
- A custom subscriber event is expected to provide the payload. Subscribe to OnGenerateCustomPayload in codeunit OutboundEventMgt_IH_TSL.
If Payload Generation Method is Custom and no prebuilt payload is provided, the publish requires a subscriber to generate payload content. If no payload is generated, processing stops with an error.
This process does not run the outbound event - it behaves as if the outbound event had been triggered.