Webhooks and Events

Webhooks and Events provide a robust mechanism for real-time integration with ERPx.

What are Webhooks and Events?

Events are notifications that the ERP system broadcasts when something significant happens - like a customer record being updated, an invoice being posted, or an order being confirmed. Webhooks are HTTP callbacks that let your applications receive these events in real-time, enabling you to build responsive, event-driven integrations.

Why use Webhooks and Events?

Instead of constantly polling the ERPx to check for changes, you can subscribe to specific events and receive instant notifications via Extension Kit. This approach:

• Reduces latency: React to changes in milliseconds, not minutes.
• Improves efficiency: Eliminates unnecessary API calls and reduces system load.
• Simplifies integration: Build loosely-coupled systems that respond to business events.
• Enables automation: Trigger workflows across multiple systems automatically.    

How it fits together?

The integration architecture comprises three core components:

1. Message Hub – The central event broker that publishes events when ERPx changes occur.
2. Event Subscriptions – Configuration that defines which events your EK tenant(s) flows want to receive.
3. Webhook Endpoints – Your HTTP endpoints that receive and process event notifications from other 3rd parties.

When a business event occurs (e.g., a sales order is created), the Message Hub publishes an event. If you have subscribed to that event type, the platform triggers your Extension Kit flow, delivering the event data to your endpoint.

flowchart LR
    A[Business Action in ERPx] --> B[Generates Message Hub Event]
    B --> C[EK Flow Triggered by Message Hub Event]
    C --> D[Flow Performs Defined Logic]

Message Hub fundamentals

Understanding event types

Event types are used to name the events emitted from the source system. Typically the name reflects the underlying business object that triggered the event to be sent. An event type is classified as either a document event or a message event.

Document Events

These represent changes to business entities and follow the pattern:

{
  "Properties": {
    "MessageType": "DocumentMessage",
    "ObjectId": "Customer2",
    "EventType": "customer",
    "PublicName": "Customer",
    "EventTypeVersion": "2.0",
    "PublicApiVersion": "1",
    "ChangeType": "Added"
    // ...
  },
  "Body": {
    // ...
  },
  "ContentType": "application/json"
}

ChangeType examples

• ChangeType: Added – A new customer record was created.
• ChangeType: Modified – An existing customer record was modified.

Message Events

Message Events represent system-level and process-oriented occurrences that don’t necessarily map to a single document change.    

Event naming and scoping

Event names are aligned with object naming. Scoping is defined by the source system. The source system identifies the U4 product, such as ERP, source to contract, etc.

Scope examples

Event versioning

Events are versioned to ensure backward compatibility.

• Format: v{major}.{minor}

Examples:

• v1.0 – Initial version
• v1.1 – Minor update (backward compatible)
• v2.0 – Major update (may include breaking changes)

Best practices:

• Always specify a version when subscribing to events.
• Monitor deprecation notices for a version’s end-of-life.
• Test thoroughly before migrating to a new major versions.

Event headers and metadata mapping

Each event published by the Message Hub includes a set of standardized headers and metadata properties. These headers provide essential context for processing and tracing events across systems.

Header mapping overview

Message body format

The body of the event is delivered in JSON format and contains the actual payload—the business entity or document affected by the event. The structure varies depending on the entity type (e.g., Customer, Invoice, SalesOrder):

"Body": {
  "customerId": "11184",
  "customerName": "vat name",
  "countryCode": "GB",
  "invoice": {
    "currencyCode": "EUR",
    "paymentTermsId": "13",
    // ...
  },
  "lastUpdated": {
    "updatedAt": "2024-09-26T18:30:06Z",
    "updatedBy": "SYSTEM"
  }
}

Webhook

Webhook trigger basics

Webhooks enable external systems to trigger automated workflows in your ERP system by sending HTTP requests. This is commonly used for scenarios like:

• Processing supplier invoices from external portals
• Integrating with third-party supplier management systems
• Automating data flows from platforms like Amazon into ERPx

How Webhooks work

When an external system sends an HTTP request to your webhook address, it automatically initiates a predefined flow in the Extension Kit Portal, allowing seamless data transfer into ERPx.

Required configuration

Available authentication methods

Choose the appropriate security level for your webhook:

Request body formats

Your webhook can accept data in three formats:

• JSON (Default and Recommended)

  • Structured data format.
  • Schema validation available.
  • Best for most integrations.

• XML

  • Legacy system support.
  • No schema validation.

• Text

  • Simple text data.
  • No schema validation.

Response configuration

Customize how your webhook responds to incoming requests:

• Status Codes:

  • 204 No Content (Default)
  • 200 OK
  • 202 Accepted

• Response Body: Set a custom message (e.g., “OK”, “Request received”).

• Content Type: Define the format of the response.

Webhook address

Located in the Extra Data section of your Extension Kit flow definition, this is the unique URI that external systems use to send data to your ERPx.

Testing your webhook with Postman

Follow these steps to verify your webhook is working correctly:

Setup steps

1. Get the webhook address from the Extra Data section in your EK flow definition:

2. Create a new Postman request:
   • Method: POST
   • URL: Paste the webhook address;
   • Authentication: Select “Basic Auth”;
   • Username: Enter the username from EK flow;
   • Password: Enter the password from EK flow.

3. Test without data:
   • Send the request;
   • You should receive: Status code 200 and response body OK;
   • This confirms the webhook is active.

3.1 Expected Results:

Success: You receive the configured status code (e.g., 200) and custom response body (e.g., “OK”):

Flow Triggered: The Extension Kit flow is triggered:

4. Test with data:
   • Add a JSON body to your request;
   • Send the request;
   • The EK flow will trigger and process the data you sent.

4.1 Expected Results:

Success: You receive the configured status code (e.g., 200) and custom response body (e.g., “OK”):

Flow Triggered: The Extension Kit flow executes with data included in the request body:

Best practices

• Always use authentication in production environments (avoid “None” option).
• Use JSON format for structured data when possible.
• Test thoroughly with Postman before connecting external systems.
• Document your webhook address securely for authorized systems only.