Webhooks

📘

Purpose

Webhooks allow external systems to receive real-time updates when relevant events occur inside facilioo. This page outlines the core concepts, key entities, and known limitations of the current webhook system.

Concept

Webhooks in facilioo are composed of several related entities working together to trigger and manage outgoing HTTP requests:

Configuration Entities

• WebhookRegistration: Defines the configuration for a webhook (target URL, events to subscribe to, grouping, and authorization).

Nested Configuration Entities

• WebhookTargetAuthorization: Stores the credentials or authentication details to be used when sending webhook requests for a particular WebhookRegistration.
• WebhookEvent: Represents a domain event that can be subscribed to via a WebhookRegistration. It consists of an entity name (as Process, Unit, etc.) and a type (see further below). A WebhookEvent is individually created for each event attached in the creation of a WebhookRegistration.

Runtime Entities

• Webhook: An instance triggered by a WebhookEvent, if the corresponding domain event happens. By being related to a WebhookEvent they are unique for each WebhookRegistration. Furthermore, each Webhook has a state which can be one of the values further below.
• WebhookAttempt: A record of each attempt to deliver a Webhook, including retry logic and response handling.

✅

Expected Usage

This documentation may appear more detailed than necessary — that’s because it includes insights into facilioo’s internal webhook handling. In most cases, you only need to create a WebhookRegistration (Recipe). This will automatically create:

• WebhookRegistration,
• WebhookTargetAuthorization,
• and one WebhookEvent per subscribed event.

All other resources (Webhook and WebhookAttempt) are runtime artifacts created by facilioo to manage the webhook lifecycle. You typically won’t interact with them unless something goes wrong — for debugging.

Use the additional endpoints to diagnose delivery issues — for example, if your system doesn’t seem to receive a webhook call. There is no direct endpoint for WebhookTargetAuthorization, as it’s managed entirely through WebhookRegistration.

Enums

WebhookEventType

The type of WebhookEvent describes the kind of domain model change that triggers the event:

WebhookState

The state of a Webhook represents the current delivery state of an individual Webhook:

Example Instance

---

Lifecycle

Once per combination of events to subscribe to and target configuration:

1. Register: Create a WebhookRegistration to specify the target URL and authorization, as well as which events to listen to. The creation of the Webhook Registration can be performed automated from within your system or manually via any HTTP-Client (like Postman or here).

Multiple instances based on the subscribed events from the registration and the actual events happening as trigger:

2. Trigger: When the specified event occurs inside the facilioo system, a Webhook entity is created.
3. Execute: The delivery of the Webhook is scheduled and executed by an instance of WebhookAttempt. If delivery fails, it is retried based on a predefined schedule.
4. Resolve: If delivery succeeds or is aborted/resolved manually, the Webhook is marked complete.

---

Authorization

WebhookTargetAuthorization supports the following:

---

Retry Mechanism

WebhookAttempts implement exponential back off retries:

---

Message Grouping

Webhooks can be delivered with grouping enabled. Grouping ensures that messages which belong together are processed in the correct order. When two or more messages are assigned to the same group:

• The delivery order is guaranteed within that group.
• A message in a group will only be delivered after all earlier messages in the same group have been successfully processed.
• Grouping is especially useful when entities have dependencies. For example:
  • A Conference and its Topics
  • A Property, its Entrances, and its Units
  • ...

By default, a failed delivery blocks all subsequent messages in the same group until the failed message has been resolved. If you enable the option “Continue after fail”, message delivery within the group will proceed even if one message could not be delivered.

Webhook registrations provide two options to configure grouping behaviour:

• ShouldGroup – If enabled, message grouping applies as described above.
• ShouldGroupContinueAfterFail – If enabled, subsequent messages in the group will still be attempted even if a prior message failed.

---

Registration

👍

Hands On

This is what's important, if you want to integrate facilioo's Webhooks into your system.

Refer to the Webhook Registration Recipe to create, trigger, and consume webhooks.

🚧

Altering a WebhookRegistration

Currently, altering targetAuthorization or enabledEvents of a WebhookRegistration isn't supported yet! If you need to change the used authorization for your targetUrl or if you want to create, update, or delete enabled events, you need to create a new WebhookRegistration and delete the existing one.

---

Known Issues

General

• Account Role Restriction: Currently, only accounts of a party with the type PropertyManagementCompany are allowed to use this feature.
• No central overview: Clients cannot currently view or manage webhook registrations and their attempts in the UI of the facilioo platform.

Webhook Registration

• No validation: The system doesn't validate whether a target URL is reachable or if the entity name is valid.
• No deduplication: Multiple identical registrations can be created.
• No clean-up: Registrations with persistent delivery failures are not removed automatically.
• Non-Altering: Enabled events and specified target authorization can not be altered. You have to create a new registration in order to change them.
• No filtering: You can not further specify conditions for a certain entity of an enabled event, like filters.

Webhook Invocation

• Event coverage incomplete: Some entities are not yet (fully) supported. These include:
  • Account
  • Tenant
  • Property (Create event not working)
  • Entrance (Create event not working)
  • Inquiry(Everything working, but the delete endpoint is not implemented, so it's unlikely the Delete event will fire)
• Own Party Context: The webhook context is bound to your own party context. Therefore, only action triggered from an account in your party (usually a coworker at the property management company or yourself) will invoke a webhook. Because, tenants and owners are their own parties, their actions won't trigger a webhook. This is very crucial in terms of inquiries and process feeds, where it's very common that tenants and parties participate, but won't trigger a webhook.
• facilioo Platform (Web/App): Actions performed via the facilioo platform (web or app) might not be properly synced into the Webhook system, despite the targeted entity is supported in general (e.g., creating a Document in an existing Process triggers no Webhook, but creating a Document in an existing Property triggers a webhook, despite all three entities being supported in general in terms of webhooks).

Recommendations

• Use POST /api/webhook-registrations/search and search by targetUrl to find active registrations for particular endpoints.
• Avoid long-living webhook registrations unless required. Consider implementing your own clean-up policy by tracking failed attempts.
• For debugging purposes of the webhook target and the HTTP-Request sent, you can use tools like PostBin or a local server with ngrok.