Realworks

Add-on

The Realworks add-on keeps Realworks objects and Sparki projects connected, and can send confirmed Sparki appointments back to a Realworks agenda.

Realworks remains the source for listing data. Sparki stores a synced copy so the dashboard can create or update customer-facing projects from it.

The Short Version

Realworks sends Sparki a webhook when an object changes. The webhook is small: it tells Sparki which integration, afdeling, and object changed, and it includes endpoint URLs for the object details. Sparki then fetches the full object from Realworks, stores it as a synced Realworks item, and makes that item available in the dashboard.

That webhook does not create a Sparki project by itself. It prepares or refreshes the Realworks item. A Sparki project is created when someone imports that Realworks item from the projects overview, or when someone selects it from an existing project and saves the project. After a project is linked, later Realworks updates can refresh the linked project with the latest synced data.

Realworks object changes
        |
        v
Webhook v2 is sent to Sparki
        |
        v
Sparki fetches the full object from Realworks
        |
        v
Sparki stores or refreshes the synced Realworks item
        |
        v
Dashboard creates or updates a linked Sparki project

Webhook v2 URL

Each Realworks integration has its own webhook URL. The URL uses the integration id, so one portal connection does not accidentally receive updates for another portal connection. Realworks needs the full absolute URL, not only the path.

https://api.sparki.app/webhooks/realworks/v2/{integrationId}

Do not copy the example above with {integrationId} still inside it. The easiest and safest way to get the correct URL is to open the Realworks add-on settings in the dashboard and copy the Webhook URL field there: open Realworks add-on settings. That dashboard field uses the configured Sparki API URL for the environment, so production uses https://api.sparki.app and local or test environments can show their own API host.

When Realworks calls this URL, Sparki accepts OBJECT_UPDATE events where userAccess is ACTIVE. Sparki reads AFDELING and OBJECT from the webhook parameters and checks that the afdeling is allowed for this integration when allowed afdeling codes are configured.

The webhook payload can contain several possible Realworks detail URLs. Sparki prefers the recommended v3 URL, then active v3, then active v2. It only uses a URL that belongs to the configured Realworks API base URL for that integration.

Settings Toggles

The Realworks settings page has a few switches. They do not all do the same thing, so use them as separate permissions for separate sync flows.

For appointment write-back, the practical setup is: turn on Agenda, turn on Outbound, save the connection, sync agenda targets, and link the Sparki parent schedule to the correct Realworks agenda target. The Agenda toggle makes the target selectable; the Outbound toggle is the permission for Sparki to write confirmed appointments back to that target.

Important operator note: the current background appointment processors use the enabled Realworks connection and the linked schedule as the hard requirements for write-back. The outbound domain is saved as the intended permission flag, but it is not the only stop lever in the current backend path. If you must stop write-back immediately, disable the Realworks connection or disconnect the affected Sparki schedule from the Realworks agenda target.

Testing Without Live Data

Use Use mock Realworks connection when you want to test the Sparki flow without touching a Realworks office. In mock mode, Sparki uses its built-in test Realworks data for listings, agendas, project linking, and appointment write-back checks.

Realworks also has Dev mode enabled for smoke testing appointment create, update, and cancel behavior. This mode is meant for local verification, the built-in mock flow, or a dedicated Realworks development tenant. It is not a general safety switch for a production Realworks office.

When dev mode is used for appointment testing, test appointments are labelled with the configured test prefix, such as [SPARKI TEST], and can use the configured smoke-test agenda values. Only point those settings at a Realworks test tenant, test afdeling, or test medewerker agenda. Do not use a production agenda for smoke tests unless the office explicitly accepts temporary test appointments there.

For a safe test phase, use this order:

1. Test the Sparki setup with Use mock Realworks connection enabled.
2. If Realworks needs to see real API traffic, ask for a dedicated development tenant, test office, or test agenda target.
3. Enable Dev mode enabled only for that dedicated test target.
4. Before switching to production, turn off mock mode and dev mode, review the agenda link, and confirm that Outbound should really create appointments in the live Realworks agenda.

Wonen, Business, and Nieuwbouw

Sparki decides what kind of Realworks item it is from the URL that Realworks sends in the webhook. A Wonen URL becomes a wonen-object, a Business or Bussiness URL becomes a business-object, and a Nieuwbouw URL becomes a nieuwbouw-object.

The type is important because Sparki stores it as part of the hidden Realworks link. It helps Sparki know whether the linked project came from Wonen, Business, or Nieuwbouw when future webhooks arrive.

Nieuwbouw is recognized as its own Realworks object type, but the visible project fields currently use the same shared object mapping as Wonen. That means Sparki copies common fields such as title, description, price, address, coordinates, details, images, and floor plans. Extra Nieuwbouw-specific fields that do not fit this mapping are kept in the original Realworks data in the background, but they do not become visible project fields today.

Before a Project Exists

When the webhook arrives, Sparki stores the Realworks object in a synced item list for that integration. The stored item includes a preview title, preview address, status, category, transaction type, thumbnail, the Realworks object code, the afdeling code, and the original Realworks response.

This gives the dashboard something reliable to select later. If the object is already known, Sparki refreshes the existing synced item instead of creating a duplicate. If an object is already linked to one or more Sparki projects, Sparki also refreshes those linked projects from the latest synced item.

Creating a Sparki Project from Realworks

In the dashboard, open Projects and choose Import Realworks. Select the synced Realworks item from the modal. Sparki creates the project directly from that item, fills the normal project fields, copies the linked images and floor plans, and stores the hidden Realworks link.

The existing project settings flow still exists for projects that were created manually first: open the project settings, choose the Realworks source, select the synced item, and save the project.

After that save, the Sparki project knows which Realworks object it came from. The hidden link stores the Realworks provider, object id, object type, object code, afdeling code, and the synced item id. This is what lets later Realworks updates find the right Sparki project again.

Synced Realworks item
        |
        v
Dashboard prefill
        |
        v
Sparki project fields are filled
        |
        v
Project is saved with hidden Realworks link
        |
        v
Later webhook updates can refresh the linked project

What Realworks Data Goes Where

The table below describes the visible project fields that Sparki fills from the synced Realworks item. The same mapping is used for Wonen, Business, and Nieuwbouw unless noted otherwise.

Sparki also stores Realworks data that is not shown directly as customer-facing project text. This includes the Realworks object id, object type, object code, afdeling code, source URL, webhook name, webhook event, webhook timestamp, selected Realworks version, and the original Realworks response. That stored link is what makes later refreshes possible.

Nieuwbouw Details

For Nieuwbouw, Sparki stores the item as a nieuwbouw-object. The visible project mapping is still the common Realworks mapping above. In practice, this means the Nieuwbouw title becomes the project title, the Nieuwbouw descriptions become the project descriptions, the Nieuwbouw price becomes the project price, and the Nieuwbouw address, coordinates, details, images, and floor plans go to the same Sparki project fields as Wonen.

If Realworks sends Nieuwbouw fields that are specific to a development, phase, building block, unit collection, or other new-build structure, Sparki keeps those fields in the original stored Realworks data. They are useful for traceability and future mapping work, but they are not automatically shown on the project today unless they also appear in one of the shared fields listed above.

Updates After Linking

When a later webhook arrives for the same Realworks object, Sparki refreshes the synced Realworks item. If that item is linked to an active Sparki project, Sparki refreshes the project fields that are managed by the Realworks link.

Realworks-managed media is tracked separately from manually added media. Sparki can update Realworks-managed images and floor plans, remove Realworks-managed media that disappeared from Realworks, and preserve media that was added manually in Sparki.

Appointments Back to Realworks

Appointment sync is a separate flow from object sync. It only runs when the Realworks connection is enabled, the Realworks API settings are complete, and the Sparki schedule is linked to a Realworks agenda target.

When the team connects a Sparki schedule to a Realworks agenda target, Sparki stores the Realworks afdeling code and medewerker id on that schedule link. If Realworks did not return a medewerker id for the selected agenda target, the dashboard asks for it during the schedule connection step. Sparki needs that id because it is sent with appointments that are created in the Realworks agenda.

When a confirmed appointment is created in Sparki, Sparki queues a create action for Realworks. When a confirmed appointment changes, Sparki queues an update action. When an appointment is cancelled, Sparki queues a cancel action if the appointment had already been synced to Realworks before.

Customer books or changes a confirmed appointment in Sparki
        |
        v
Sparki queues a Realworks agenda sync
        |
        v
Sparki checks the linked Realworks agenda
        |
        v
Sparki sends create, update, or cancel to Realworks agenda v3
        |
        v
Sparki stores the Realworks agenda item id for later updates

For a new appointment, Sparki sends a create request to Realworks agenda v3. For an update or cancellation, Sparki sends an update request to the Realworks agenda item that was stored after the first successful sync. If an update cannot find the old Realworks agenda item, Sparki can create a new one instead.

The appointment message sent to Realworks includes the afdeling code, medewerker id, agenda type, status, privacy value, subject, description, start time, end time, Sparki appointment id, customer name, customer email, customer phone, linked Realworks object information when the project is linked, and the target Realworks agenda information.

After Realworks accepts the appointment, Sparki stores the Realworks agenda item id. That id is used for future updates or cancellations, so the same customer appointment remains connected across both systems.