📘
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:

ID	Type	Description
`1`	`Created`	A new entity was created in the system.
`2`	`Updated`	An existing entity was updated.
`3`	`Deleted`	An entity was deleted.
`4`	`ReplaceRelation`	Not supported yet!
`5`	`AddToRelation`	Not supported yet!
`6`	`RemoveFromRelation`	Not supported yet!

`WebhookState`

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

ID	State	Description
`1`	Created	`Webhook` has been created but not yet delivered.
`2`	Retrying	Delivery has failed and is scheduled to be retried.
`3`	Successful	`Webhook` was delivered successfully (2xx status code).
`4`	Failed	All retry attempts have failed; `Webhook` is considered failed.
`5`	Aborted	`Webhook` was manually marked as aborted and will not be retried.
`6`	Pending	`Webhook` is waiting for grouping or scheduling.
`7`	Resolved	`Webhook` issue has been manually resolved.

Example Instance

Example instance of a single, unauthorized `WebhookRegistration` with multiple `WebhookEvents` that are each triggered once and handled individually. The `Webhook` itself has also a reference to the `WebhookRegistration` that has been omitted in this diagram.

Lifecycle

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

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:

Trigger: When the specified event occurs inside the facilioo system, a Webhook entity is created.
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.
Resolve: If delivery succeeds or is aborted/resolved manually, the Webhook is marked complete.

Authorization

WebhookTargetAuthorization supports the following:

ID	Name	Description
`0`	No Auth	Assumes your endpoint is publicly available.
`1`	Basic Auth	The combination of username and password will be joined with a colon (`:`) and base64 encoded to then be sent as basic auth within the `Authorization` header. Structure: `'Authorization: Basic ' + b64encode("{<username>}:{<password>}")` Example: `Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==`
`2`	Platform signed Bearer Token in Header	Attaches a Bearer token to the request's `Authorization` header, issued and signed by the facilioo platform. It can be used to fetch further information from the facilioo API for the given `partyId` of the `WebhookRegistration` and is usually valid 30 minutes. It is an access tokens for and from our system that can be verified with the public keys found here. Structure: `'Authorization: Bearer ' + token` Example: `Authorization: Bearer eyJhbGci.OiJIUzI5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYiv...`
`3`	Platform signed Bearer Token in Body	Attaches a Bearer token to the request's body as the attribute `platformSignedBearerToken`, issued and signed by the facilioo platform. It can be used to fetch further information from the facilioo API for the given `partyId` of the `WebhookRegistration` and is usually valid 30 minutes. It is an access tokens for and from our system that can be verified with the public keys found here Structure: `{ "platformSignedBearerToken": token }` Example: `{ "platformSignedBearerToken": "eyJhbGci.OiJIUzI5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYiv..." }`
`4`	Target API Token	Attaches a provided access token to the Target API to the `x-api-key` header of the request to the target url. Structure: `'x-api-key: token` Example: `x-api-key: abcdef12345`

Retry Mechanism

WebhookAttempts implement exponential back off retries:

Attempt	Wait Time after previous fail
1 (first)	scheduled instantly
2	5 min
3	15 min
4	1 hour
5	6 hours
6	12 hours
7 (last)	24 hours

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.
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.