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 selects that Realworks item in the dashboard 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.

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, the team chooses a synced Realworks item and asks Sparki to prefill a project from it. Sparki turns the Realworks data into normal project fields, then the project is saved with a hidden Realworks link.

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.