generated: '2026-08-26'
method: searched
source: https://www.nextw.com/docs/developerstudiointeroperability
name: Nextworld event and webhook surface
asyncapi_published: false
asyncapi_note: >-
  Nextworld publishes no AsyncAPI document. Probed /asyncapi.yaml, /asyncapi.json and the docs
  sitemap (274 URLs) on 2026-08-26 — nothing. The event surface below is a documented catalog, not a
  machine-readable spec, and no AsyncAPI pointer is emitted. Nothing is fabricated into AsyncAPI shape.
surfaces:
- direction: outbound
  name: Event emissions
  description: >-
    Events (event emissions and subscriptions) communicate business-data changes to external targets
    and to internal logic blocks. An event definition names what initiates the event, what business
    data goes in the payload, and which targets receive it; event rules filter the payload and route
    it.
  triggers:
  - type: Workflow State Change
    description: >-
      Fires when a record's workflow state changes. The definition names the Workflow To State and
      Workflow To State Type, and can be narrowed by Workflow Type.
  - type: User-Defined Event
    description: >-
      Fired explicitly from a logic block. If the logic block later throws, the whole block including
      the queued event is rolled back and nothing is emitted.
  targets:
  - type: AWS EventBridge
    external: true
    description: >-
      An Event Bus in the customer's own AWS account receives the emitted payload. The customer must
      configure their AWS account to allow Nextworld to send events.
  - type: Logic Block
    external: false
    description: Runs platform logic when the event fires.
  delivery:
    ordering: >-
      For a workflow state change the order is - post-transition logic blocks execute, events are
      queued, the transaction commits, then events are picked up asynchronously in their own
      transaction boundaries.
    retry: Failed event targets are automatically retried several times before the Event Target record is left errored.
    replay: Failures can be resubmitted from the Event Status Inquiry application once the cause is fixed.
  payload:
    shape: customer-defined
    note: >-
      Payload fields are chosen per event definition from the driving table, keyed by a Payload Key.
      A workflow-state-change event over a Standard table may include a single entry; a Header Detail
      may include Header and Detail. A user-defined event may configure up to five payloads. Because
      the shape is defined by each customer's own tables, there is no universal event schema to
      publish — which is why no AsyncAPI exists.
  applications:
  - Event Definitions
  - Event External Target Definitions
  - Event Rules
  - Event Status Inquiry
  - Event Target Delivery Status
- direction: inbound
  name: Webhooks
  description: >-
    External systems send webhook notifications INTO Nextworld when events occur, so platform
    business logic executes in response without polling. The receiving URL is generated by the
    Webhook Setup application and pasted into the external system.
  authentication:
  - type: HMAC
    description: >-
      A secret is generated in the Credential Management application, referenced in Webhook Setup and
      configured in the external system; each inbound request is authenticated with the specified
      HMAC algorithm.
  - type: Basic Auth
    description: Each inbound request carries a username and password.
  mapping:
    manual: Data Mapper drag-and-drop from request body/header into the event definition payload.
    advanced: >-
      A Data Mapping logic block taking one JSON Object input and returning a record shaped like the
      event definition's table.
  binding: >-
    A webhook is bound to a User-Defined event definition, which is what actually carries the data
    into the platform.
  observability:
    log: Webhook Log Inquiry — successful and unsuccessful requests, with setup/definition record names, timestamp, host, source IP and request body.
    default: Only unsuccessful events are logged unless logging for successful events is enabled in Webhook Setup.
    replay: Replay Request row action re-initiates the event after the cause is fixed.
  applications:
  - Credential Management
  - Event Definitions
  - Webhook Definitions
  - Webhook Setup
  - Webhook Log Inquiry
correlation:
  field: nwCorrelationId
  note: Automatically associated with webhooks, workflow transitions, jobs, events and endpoint calls; see ../conventions/nextworld-conventions.yml.
evidence:
- url: https://www.nextw.com/docs/developerstudiointeroperability
  status: 200