Cloud Events API Reference

Overview

The Origo Cloud Events extension provides API endpoints for managing and processing cloud event messages following the CloudEvents specification. This document describes all available API endpoints and supported message types.

Namespace: Origo.PTE.CloudEvents API Publisher: origo API Group: cloudEvent API Version: v1.0

API Endpoints

1. Cloud Event Data API — Response Data

Purpose: Returns the response data content for a given message.

Endpoint Details:

• Entity Name: response
• Entity Set Name: responses
• Base URL: /api/origo/cloudEvent/v1.0/responses
• Access: Read-only (no insert or modify operations)

Fields:

Supported Operations:

• GET (single): Retrieve response data for a specific message by ID
• GET (collection): Retrieve all response data entries

Example Request:

GET /api/origo/cloudEvent/v1.0/responses('{message-id}')

1b. Cloud Event Request Data API — Request Payload

Purpose: Returns the original request data payload for a given message. Useful for inspecting or re-replaying what was sent.

Endpoint Details:

• Entity Name: request
• Entity Set Name: requests
• Base URL: /api/origo/cloudEvent/v1.0/requests
• Access: Read-only (no insert or modify operations)

Fields:

Supported Operations:

• GET (single): Retrieve request payload for a specific message by ID
• GET (collection): Retrieve all request data entries (filtered to the current user)

Preferred — fetch the raw payload directly (no prior lookup needed):

GET /api/origo/cloudEvent/v1.0/requests('{message-id}')/data
Authorization: Bearer {token}

Or fetch the OData record (returns the id and data fields as JSON):

GET /api/origo/cloudEvent/v1.0/requests('{message-id}')
Authorization: Bearer {token}

Security: Results are automatically filtered to records created by the calling application (SystemCreatedBy = UserSecurityId()).

2. Cloud Event Queue API

Purpose: Create message requests and get status for queued (asynchronous) messages.

Endpoint Details:

• Entity Name: queue
• Entity Set Name: queues
• Base URL: /api/origo/cloudEvent/v1.0/queues
• Processing Mode: Asynchronous (messages are scheduled for background processing)

Fields:

Supported Operations:

POST - Create Queue Message

Creates a new message request that will be processed asynchronously.

Request Body:

{
  "specversion": "1.0",
  "type": "Help.Tables.Get",
  "source": "MyIntegrationApp v1.0",
  "lcid": 1033
}

Response: Returns the created message with assigned ID and timestamp. Once processing is complete, the data field will contain the download URL to retrieve the response data.

GET - Retrieve Queue Messages

Retrieves queued messages (messages with an assigned Task ID).

Example Request:

GET /api/origo/cloudEvent/v1.0/queues

PATCH - Update Queue Message

Not typically used for this API.

Queue API Actions

RetryTask

Retries the processing of a cloud event message.

Endpoint:

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.RetryTask

Description: Attempts to reprocess a failed or completed message. If the task is already running it will not be restarted.

Status Values:

CancelTask

Cancels the scheduled task for a cloud event message.

Endpoint:

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.CancelTask

Description: Cancels a running or scheduled background task. If no task is scheduled, the action returns immediately.

Status Values:

GetStatus

Gets the status of a cloud event message.

Endpoint:

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.GetStatus

Status Values:

• Created: Message is still running/processing
• Deleted: No task is scheduled
• Updated: Task has been completed and results are available
• None: Message status is not known

HTTP Status Codes:

The GetStatus action returns standard HTTP status codes based on the message state:

Response: Returns the current processing status via the WebServiceActionContext.

3. Cloud Event Task API

Purpose: Create and process cloud event messages synchronously (immediate processing).

Endpoint Details:

• Entity Name: task
• Entity Set Name: tasks
• Base URL: /api/origo/cloudEvent/v1.0/tasks
• Processing Mode: Synchronous (messages are processed immediately upon creation)

Fields:

Supported Operations:

POST - Create and Process Task

Creates a new message and processes it immediately. The response will contain the download URL to the response data in the data field.

Request Body:

{
  "specversion": "1.0",
  "type": "Help.Fields.Get",
  "source": "MyIntegrationApp v1.0",
  "subject": "Customer",
  "datacontenttype": "application/json",
  "data": "{\"tableName\":\"Customer\"}"
}

Response: Returns the message with the download URL to the response data in the data field.

GET - Retrieve Task Messages

Retrieves task messages (messages without an assigned Task ID).

Example Request:

GET /api/origo/cloudEvent/v1.0/tasks

Message Types

The Cloud Events extension supports the following message types for data operations and business workflows:

Extensibility: This extension can be extended with custom implementations for additional message types by implementing the Cloud Event Msg Interface. All built-in message types require JSON format in the data field for request parameters.

Message Type Categories

For detailed documentation, see the specialized reference documents:

• Data Message Types - Data operations for retrieving and updating Business Central records
• Metadata Message Types - Schema discovery and API metadata operations
• Sales Message Types - Business operations for sales, customers, and items
• Purchase Message Types - Business operations for purchase orders and receipts
• Finance Message Types - Finance operations for general journals and fixed asset journals including validation and posting
• Inventory Message Types - Item journal operations including setup, validation, and posting
• Projects Message Types - Project (job) journal operations including setup, validation, and posting
• Resources Message Types - Resource journal operations including setup, validation, and posting
• IncomingDocument Message Types - Operations for creating, attaching, processing, and retrieving Incoming Documents
• Approval Message Types - Document approval operations including sending, approving, rejecting, delegating, and retrieving approval entries
• Memory Message Types - Persistent key-value blob storage scoped to company or user

All Available Message Types

Events and Webhooks

The Cloud Events extension provides External Business Events that enable external systems to receive webhook notifications when messages complete or fail processing. This eliminates the need for continuous polling and enables true event-driven architectures.

Webhook Notifications

Event Pattern: Minimal Notification + API Fetch

1. Message Submitted: External system submits message to Queue API or Task API
2. Processing: Business Central processes the message asynchronously (Queue API) or synchronously (Task API)
3. Event Raised: When processing completes or fails, BC raises an External Business Event
4. Webhook Notification: Subscribed endpoints receive minimal notification (MessageId, MessageType, Timestamp)
5. Data Retrieval: External system calls Data API using MessageId to fetch full response

Available Events

Configuration

Configure webhook subscriptions via Business Central's Event Subscriptions page:

1. Navigate to Event Subscriptions
2. Create new subscription
3. Select event: CloudEventMessageCompleted or CloudEventMessageFailed
4. Set Event Category: "Origo Cloud Event"
5. Configure endpoint URL and authentication
6. Enable subscription

Complete Documentation

For comprehensive webhook setup, security considerations, code examples, and troubleshooting:

→ See Events and Webhooks Reference

Includes:

• Webhook payload specifications
• Event subscription setup guide
• Integration event documentation (for BC extensions)
• Security best practices
• Example implementations (Node.js, C#, Python)
• Troubleshooting guide

Authentication

All API endpoints require proper authentication using OAuth 2.0 or Basic Authentication as configured in Business Central.

Required Permissions:

• Users must have appropriate permissions defined in the Cloud Events Full permission set or equivalent permissions to access cloud event functionality.

Data Isolation — Entra Application Boundary

All Cloud Events endpoints (/tasks, /queues, /responses, /requests) enforce strict data isolation at the Entra Application level.

Every response is automatically filtered server-side to records where SystemCreatedBy = UserSecurityId(). UserSecurityId() in Business Central resolves to the Object ID of the Entra Application (Client ID) that authenticated the request.

Consequences:

This isolation is unconditional — it cannot be overridden by OData filters, admin credentials, or any other mechanism. It applies to GET (listing and single-record reads) on all four endpoints.

Usage Examples

Example 1: Get List of Tables (Synchronous)

Request:

POST /api/origo/cloudEvent/v1.0/tasks
Content-Type: application/json

{
  "specversion": "1.0",
  "type": "Help.Tables.Get",
  "source": "MyIntegrationApp v1.0",
  "datacontenttype": "application/json",
  "data": "{}"
}

Response:

{
  "@odata.context": "...",
  "specversion": "1.0",
  "type": "Help.Tables.Get",
  "source": "MyIntegrationApp v1.0",
  "id": "12345678-1234-1234-1234-123456789abc",
  "time": "2026-02-19T10:30:00Z",
  "subject": "",
  "datacontenttype": "text/json",
  "data": "/api/origo/cloudEvent/v1.0/responses(12345678-1234-1234-1234-123456789abc)"
}

Example 2: Get Table Fields (Asynchronous)

Step 1: Queue the Request

POST /api/origo/cloudEvent/v1.0/queues
Content-Type: application/json

{
  "specversion": "1.0",
  "type": "Help.Fields.Get",
  "subject": "Customer",
  "source": "MyIntegrationApp v1.0",
  "datacontenttype": "application/json",
  "data": "{\"tableName\":\"Customer\"}"
}

Step 2a: Option 1 - Poll for Status

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.GetStatus

Step 2b: Option 2 - Webhook Notification (Recommended)

Subscribe to the CloudEventMessageCompleted event and receive automatic notification when processing completes:

{
  "MessageId": "{message-id}",
  "MessageType": "Help.Fields.Get",
  "ResponseContentLink": "/api/origo/cloudEvent/v1.0/responses({message-id})/data",
  "Timestamp": "2026-03-08T14:30:22Z"
}

Step 3: Retrieve Results

GET /api/origo/cloudEvent/v1.0/responses('{message-id}')

Note: For webhook setup, see Events and Webhooks Reference.

Example 3: Get Modified Records

Request:

POST /api/origo/cloudEvent/v1.0/tasks
Content-Type: application/json

{
  "specversion": "1.0",
  "type": "Data.RecordIds.Get",
  "source": "DataSync Service v2.1",
  "datacontenttype": "application/json",
  "data": "{\"tableName\":\"Customer\",\"startDateTime\":\"2026-02-01T00:00:00Z\",\"endDateTime\":\"2026-02-19T23:59:59Z\"}"
}

Example 4: Get Available Message Types

Request:

POST /api/origo/cloudEvent/v1.0/tasks
Content-Type: application/json

{
  "specversion": "1.0",
  "type": "Help.MessageTypes.Get",
  "source": "MyIntegrationApp v1.0",
  "datacontenttype": "application/json",
  "data": "{}"
}

Response:

{
  "@odata.context": "...",
  "specversion": "1.0",
  "type": "Help.MessageTypes.Get",
  "source": "my-application",
  "id": "12345678-1234-1234-1234-123456789abc",
  "time": "2026-02-25T10:30:00Z",
  "subject": "",
  "datacontenttype": "text/json",
  "data": "/api/origo/cloudEvent/v1.0/responses(12345678-1234-1234-1234-123456789abc)"
}

Note: The data field contains a download URL. Retrieve the actual response data by calling the URL.

Example 5: Get Help Documentation for a Message Type

Request:

POST /api/origo/cloudEvent/v1.0/tasks
Content-Type: application/json

{
  "specversion": "1.0",
  "type": "Help.Implementation.Get",
  "subject": "Help.Fields.Get",
  "source": "my-application",
  "datacontenttype": "application/json"
}

Response:

{
  "@odata.context": "...",
  "specversion": "1.0",
  "type": "Help.Implementation.Get",
  "source": "my-application",
  "id": "12345678-1234-1234-1234-123456789abc",
  "time": "2026-02-25T10:35:00Z",
  "subject": "Help.Fields.Get",
  "datacontenttype": "text/markdown",
  "data": "/api/origo/cloudEvent/v1.0/responses(12345678-1234-1234-1234-123456789abc)"
}

Note: The data field contains a download URL. Retrieve the actual markdown help documentation by calling the URL.

Error Handling

Common Error Scenarios

1. Table Not Found

• Error: "Table {tableName} not found."
• Occurs when requesting fields or records for a non-existent table

1. Invalid Message Type

• Occurs when the specified type is not supported for the requested operation

1. Missing Required Fields

• Occurs when required fields like type or specversion are not provided

Best Practices

1. Choosing Between Queue and Task APIs:

• Use Task API for immediate results and simple operations
• Use Queue API for long-running operations or bulk processing

1. Message Types:

• All Help.* message types are designed for data retrieval and metadata discovery
• Use Help.MessageTypes.Get to discover all available message types and their capabilities
• Use Help.Implementation.Get to retrieve detailed help documentation for specific message types
• Message direction is set to Outbound for all Help.* implementations

1. Content Types:

• Use application/json for structured data payloads
• Response content type is automatically set to text/json

1. Status Checking:

• For queued messages, check status before retrieving results
• Use the GetStatus action to determine if processing is complete

1. Date/Time Filtering:

• Use ISO 8601 format for date/time values
• All times should be in UTC

Version History

Version 1.0.0.0 - Initial release

• Cloud Event Data API
• Cloud Event Queue API
• Cloud Event Task API
• Data.Records.Get message type
• Data.Records.Set message type
• Data.RecordIds.Get message type
• Help.Tables.Get message type
• Help.Fields.Get message type
• Help.MessageTypes.Get message type
• Help.Implementation.Get message type
• Help.Permissions.Get message type
• Customer.CreditLimit.Get message type
• Item.Availability.Get message type
• Item.Price.Get message type
• Sales.Document.Release message type

© Origo – Cloud Events Base Extension