Skip to main content

Webhooks & Notifications

First-time workspace setup

Provision outbound webhook URLs and inbound signing secrets with [email protected] after Getting Started — Recommended Setup Sequence steps 11–15 and Onboarding a New Property — Step 7 — callbacks assume live externalId mapping (Property & Unit Mapping) and stable partial listing shapes (Listings & Availability). Steps 11–12 (Integrations, Tenant categories default for integrations) should be set before high-volume booking.* traffic. Guide pairing after go-live: Setup sequence after go-live (hub: API Reference — Setup sequence after go-live).

Finding your way in this guide

Start with Inbound vs outbound and Webhook Events, then Webhook Configuration and Inbound partner webhooks (Vivin receives) for signing. Event timing follows the enqueue pipeline in Booking Lifecycle & Validations. listing.updated and unavailability.* payloads align with Listings & Availability; inbound partner posts reuse signing from Authentication. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Handling a Late Payment collections, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Webhooks & Notifications section cross-reference · API Reference — API guide cross-reference.

Vivin supports outbound integration webhooks for partner platforms that need real-time updates instead of polling listing and booking data.

Not the in-app Notifications module

Operators see booking, payment, and ticket alerts in the management Notifications module (/notifications) and the Dashboard bell slide-over — including payment overdue rows that row-click into Handling a Late Payment — Step 1. Those are in-app history rows, not HTTP callbacks to your servers. This page covers API integration webhooks only.

Inbound vs outbound​

Pair with other Webhooks & Notifications sections

Outbound booking.* timing follows Booking Lifecycle & Validations. Inbound HA/Uniplaces routes share Bearer auth with Authentication. Full endpoint map: Webhooks & Notifications section cross-reference.

DirectionWho calls whomExamples
Outbound (Vivin → you)Vivin POSTs to the HTTPS endpoint you provide during onboardingbooking.created, listing.updated, unavailability.* in the Webhook Events table
Inbound (partner → Vivin)A channel posts to Vivin’s integration routesHousing Anywhere and Uniplaces POST …/{landlordKey}/webhook (integration Swagger on your API host)

Configure outbound URLs and auth with the Vivin team. Inbound paths and secrets are documented per integration (for example UNIPLACES_WEBHOOK_X_API_KEY on Uniplaces webhooks).

Delivery path​

flowchart LR
  Vivin[Vivin Core]
  EP[Your HTTPS webhook endpoint]
  Vivin -->|"POST signed payload"| EP

Your endpoint should accept HTTPS POST requests on the URL agreed during onboarding, validate Vivin’s authentication (shared secret header, Basic auth, or the method you configured), and return a 2xx response quickly; process heavy work asynchronously so Vivin can retry safely on transient failures.

Webhook Events​

Pair with other Webhooks & Notifications sections

unavailability.* payloads mirror partial ListingDto rows — Listings & Availability. Polling fallback when outbound is unavailable: Polling as an Alternative. Full endpoint map: Webhooks & Notifications section cross-reference.

The following events can be pushed to your platform if a webhook endpoint is configured:

EventDescriptionWhen it fires
booking.createdA new booking was created on a listing mapped to your platformBooking created from any source (Vivin UI, another platform, booking engine)
booking.cancelledA booking was cancelledProperty manager or tenant cancels via Vivin
listing.updatedListing pricing or availability changedProperty manager updates rent, dates, or availability
unavailability.createdNew calendar block addedManual block or booking from another channel
unavailability.removedCalendar block removedBooking cancelled or manual block removed

Webhook Configuration​

Pair with other Webhooks & Notifications sections

Provision outbound URLs with Vivin during onboarding — see Get Help & Support. Inbound Channex uses revisions feed, not POST …/webhook — Channex booking revisions feed. Full endpoint map: Webhooks & Notifications section cross-reference.

Webhook endpoints are configured during onboarding by the Vivin team. Provide:

  1. Endpoint URL - HTTPS endpoint on your platform that accepts POST requests
  2. Events - Which events you want to receive
  3. Authentication - How Vivin should authenticate to your endpoint (e.g. shared secret header, Basic auth)

Webhook Payload Format​

{
  "event": "booking.created",
  "timestamp": "2026-04-20T10:30:00.000Z",
  "data": {
    "externalId": "abc-123",
    "bookingId": "vivin-booking-uuid",
    "checkInDate": "2026-09-01",
    "checkOutDate": "2027-01-31",
    "status": "confirmed"
  }
}

Inbound partner webhooks (Vivin receives)​

Pair with other Webhooks & Notifications sections

landlordKey on inbound paths must match account stored key — Full listing feeds — landlordKey. Try payloads in Integration Swagger per Try requests in Swagger. Full endpoint map: Webhooks & Notifications section cross-reference.

Channels that push booking lifecycle events into Vivin use integration-scoped routes on your Core API host (same host as GET /listings and POST /bookings). Each route is documented in its own integration Swagger UI:

IntegrationSwagger UI pathInbound webhook route
Housing Anywhere{API host}/housinganywhere-integrationPOST /housinganywhere-integration/{landlordKey}/webhook
Uniplaces{API host}/uniplaces-integrationPOST /uniplaces-integration/{landlordKey}/webhook

Replace {API host} with your environment base URL (for example the host your management app uses for API calls). {landlordKey} is the account’s stored landlord key — it must match the account that owns the listing referenced in the payload (same pattern as Uniplaces / Housing Anywhere full-feed URLs).

Channex booking revisions feed​

Channex inbound bookings use Channex’s booking revisions feed (PMS polling pattern), not an operator-configured POST …/webhook route on Vivin like Housing Anywhere or Uniplaces.

TopicDetail
DirectionChannex → Vivin (Vivin pulls unacknowledged revisions on a schedule)
MappingEach Vivin unit needs listing_integration.channexMapping with Channex propertyId, roomTypeId, and ratePlanId UUIDs — provisioned with Vivin support, not self-serve on Listings > Channels
CreatesNew confirmed revisions queue a Channex booking import when customer.mail and stay dates are present
CancelsCancelled revisions cancel the matching active Vivin booking when found
ModifiedModified revisions are acknowledged on the Channex side only — Vivin does not auto-apply date or amount changes yet
Partner APIChannex partners can still GET /channex-integration/listings and POST /channex-integration/bookings per API Reference

Operator setup: enable Channex under Settings > Integrations and confirm UUID mapping with your Vivin contact. See also Integrations (concepts).

Housing Anywhere​

Housing Anywhere posts paid and cancelled booking notifications. Vivin maps notification_type (for example booking_paid) and listing references such as listing_external_reference to the correct account listing, then queues or idempotently accepts the booking.

TopicDetail
Method & pathPOST /housinganywhere-integration/{landlordKey}/webhook
AuthAuthorization: Bearer with the same Housing Anywhere integration secret as other HA routes (HOUSINGANYWHERE_INTEGRATION_SECRET). Inbound signing/HMAC hardening is tracked internally (VIVIN#797).
PayloadPartner JSON — see HousingAnywhereWebhookDto in Swagger (notification_type, booking_id, dates, listing_external_reference, tenant contact fields, amounts in cents).
Response{ "ok": true, "message": "…" } when accepted or treated as a no-op

Integration Swagger — Housing Anywhere POST webhook expanded with path parameter and request body schema

Uniplaces​

Uniplaces sends lifecycle events (for example booking paid, booking cancelled) with an event discriminator and offer/listing identifiers that map to Vivin externalId values.

TopicDetail
Method & pathPOST /uniplaces-integration/{landlordKey}/webhook — {landlordKey} must be the account’s stored landlordKey (not the integration email used on some full-feed poll URLs). See Full listing feeds — landlordKey.
AuthAuthorization: Bearer (integration JWT, same family as other Uniplaces sync-out routes) and/or x-api-key when UNIPLACES_WEBHOOK_X_API_KEY is configured server-side
PayloadPartner JSON — see UniplacesWebhookDto in Swagger (event, offer_id, booking_id / booking_Id, guest fields, move dates, optional booking_total in cents). Event names may use hyphens or underscores (booking-paid vs booking_paid).
Response{ "ok": true, "message": "…" } on success — see Actioned vs acknowledged below

Actioned events — Vivin creates a booking on payment-style events (booking-paid, booking_paid, payment_confirmed, and normalized variants) and cancels on cancel/reject events (booking-cancelled, booking-canceled, booking-rejected, and normalized variants).

Acknowledged without action — Every other Uniplaces lifecycle event (booking-created, booking-accepted, booking-confirmed, booking-discarted, booking-payment-expired, booking-expired, and so on) returns HTTP 200 with { "ok": true, "message": "Ignored Uniplaces event: …" }. Vivin logs and acknowledges them so Uniplaces does not treat the delivery as failed and disable the webhook. Vivin only imports bookings on payment and removes them on cancel/reject — earlier lifecycle signals are intentionally no-ops.

Integration Swagger — Uniplaces POST webhook expanded with landlordKey path parameter and request body schema

Try it out in Swagger

Open the integration Swagger URLs above, use Authorize with your integration Bearer token (see Authentication), expand the webhook POST operation, and use Try it out with a sandbox payload before wiring the partner’s production callback URL.

Platform-Specific Webhooks (summary)​

PlatformDirectionFormat
Housing AnywhereInbound → VivinPartner notification_type payload at POST …/{landlordKey}/webhook (see above)
UniplacesInbound → VivinPartner event payload at POST …/{landlordKey}/webhook (see above)
ChannexInbound → VivinVivin polls Channex booking revisions feed (see Channex booking revisions feed) — not a Vivin-hosted inbound webhook
Your platform (onboarding)Outbound ← VivinStandard Vivin envelope in Webhook Payload Format (event, timestamp, data)

Polling as an Alternative​

Pair with other Webhooks & Notifications sections

Compare updatedAt on partial pulls — Listings & Availability — Sync Strategy. Retry policy when your endpoint returns 5xx: Error Handling. Full endpoint map: Webhooks & Notifications section cross-reference.

If your platform does not support incoming webhooks, you can poll the GET /listings endpoint at regular intervals (recommended: every 15-30 minutes) to detect changes in pricing, availability, and calendar blocks. Compare the updatedAt timestamp to identify modified listings since your last sync.

Webhook vs Polling

Webhooks provide near-real-time updates (seconds) while polling introduces a delay equal to your polling interval. For availability-critical integrations, webhooks are strongly recommended to minimize double-booking risk.

Webhooks & Notifications section cross-reference​

Use this table when one webhook topic naturally leads into another API guide, operator UI, or downstream workflow — each row links to the docs you should read before or after wiring callback handlers.

API topic / sectionPair with these docs
Inbound vs outboundBooking Lifecycle & Validations, Authentication
Webhook EventsListings & Availability, Creating Bookings, Notifications — Payment overdue alerts → Handling a Late Payment — Step 1 (in-app operator rows, not outbound HTTP), Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent)
Webhook ConfigurationGet Help & Support, Settings > Integrations
Inbound partner webhooks (Vivin receives)Full listing feeds — landlordKey, Try requests in Swagger
Polling as an AlternativeListings & Availability — Sync Strategy, Error Handling

| Lockout catch-up after password recovery | Webhook alert backlog after sign-in recovery | Common Workflows — Lockout catch-up, Notification triage, Management session | | Pending manual receipt approval | Webhook imports with pending receipts | Common Workflows — Pending manual receipt approval, Booking Lifecycle & Validations, Finance — Pending manual payments | | Reject/revert mistaken receipts | Duplicate webhook deliveries | Common Workflows — Reject/revert mistaken receipts, Cancelling a Booking, Payment Allocation — Correcting mistaken receipts | | Portfolio segmentation by tenant category | Segment triage on webhook imports | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Bookings — Other filters | | Notification row-click navigation | Webhook events vs /notifications row-click | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | booking.* events vs payment overdue | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Inbound events vs confirmation alerts | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Webhook imports vs Debt Aging | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Webhook batch payment overdue → collections Steps 1–6 | | Finance Income status drill-down | Event timing vs Income segments | API Reference — Finance Income status drill-down, Common Workflows — Finance Income status drill-down, FAQ — Finance Income status drill-down hub | | Cash flow forecast drill-down | Callback lag vs forecast bars | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Webhooks & Notifications guide sections

Related below links outbound events and inbound signing to setup, companion API guides, operator workflows, and escalation paths. Pair Setup sequence after go-live with Getting Started — Recommended Setup Sequence; pair Companion API guides with API Reference hub. Topic-to-guide pairing in sections above: Webhooks & Notifications section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Webhooks & Notifications guide sections

Complete Account Settings — Recommended setup order before partner traffic. Hub parity: API Reference — Setup sequence after go-live. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Documentation map & escalation​

Pair with other Webhooks & Notifications guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Full pairing matrix: Webhooks & Notifications section cross-reference.

Companion API guides​

Pair with other Webhooks & Notifications guide sections

Companion guides share Bearer authorization or error shapes with this page — start from API Reference hub. Full pairing matrix: Webhooks & Notifications section cross-reference.

  • Booking Lifecycle & Validations — Validation steps before a booking record is created from the integration API
  • Creating Bookings — How POST …/bookings is queued and what happens after a successful run
  • Listings & Availability — Polling GET /listings when you cannot accept inbound webhooks; partial pulls whose unavailabilities change trigger unavailability.* events
  • Full listing feeds — Partner-shaped publish payloads that emit listing.updated webhook events
  • iCal feeds — Outbound calendar URLs when partners poll instead of accepting unavailability.* webhooks
  • Authentication — Bearer tokens and scopes for integration traffic
  • Error Handling — When your webhook endpoint should return retryable 5xx vs permanent 4xx
  • Property & Unit Mapping — External listing keys before enqueueing POST …/bookings
  • Booking engine integration — White-label reservation webhooks when POST /bookings succeeds on engine traffic
  • Management session — Operator JWT patterns when testing webhook handlers against Core API
  • AI usage — Operator-only LLM ledger (not partner integration Bearer keys)

Upstream & downstream workflows​

Pair with other Webhooks & Notifications guide sections

Workflow bullets pair with Common Workflows — Workflow cross-reference after partner traffic lands in the management app. Full pairing matrix: Webhooks & Notifications section cross-reference.

Operator UI & settings​

Pair with other Webhooks & Notifications guide sections

Operator UI rows validate the same inventory and permissions behind integration HTTP — pair with Account Settings — Tab cross-reference. Full pairing matrix: Webhooks & Notifications section cross-reference.

Deeper concept reads​

Pair with other Webhooks & Notifications guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Deeper workflow reads​

Pair with other Webhooks & Notifications guide sections

Workflow reads pair with Common Workflows hub subsection index and Workflow cross-reference. Each workflow sub-guide also has its own Deeper API reads subsection with reciprocal companion API anchors — hub parity: API Reference — Deeper workflow reads. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Webhooks & Notifications guide sections

Outbound booking.* events may queue during operator lockout — triage in-app alerts after sign-in recovery before replaying callbacks. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: webhooks--notifications-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Webhooks & Notifications guide sections

booking.* webhooks do not encode receipt approval state — pair with Finance — Pending manual payments. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: webhooks--notifications-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Webhooks & Notifications guide sections

Duplicate booking.created deliveries pair with Cancelling a Booking and receipt Reject / Revert. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: webhooks--notifications-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Webhooks & Notifications guide sections

Webhook payloads include booking ids — segment operator triage with Bookings — Other filters. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: webhooks--notifications-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Webhooks & Notifications guide sections

Outbound booking.* webhooks complement /notifications row-click — operators still triage in-app rows when callbacks lag. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Webhooks & Notifications guide sections

Webhook-driven imports surface payment overdue in-app rows — row-click into booking Transactions before Debt Aging. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Webhooks & Notifications guide sections

booking.created webhooks often pair with Upcoming confirmation alert triage — callbacks do not approve confirmation receipts. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Webhooks & Notifications guide sections

High-volume webhook imports inflate receivables — triage Top debtors after row-click when callback batches backlog. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

booking.* webhook events that enqueue payment overdue in-app rows still need operator Handling a Late Payment — Steps 1–6 after receivables triage. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: webhooks--notifications-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Webhooks & Notifications guide sections

Webhook enqueue timing may skew Income → Scheduled — segment-click reconcile after inbound partner posts settle. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Webhooks & Notifications guide sections

Webhook payment events vs Cash flow forecast collections bars — operator approval still gates month-bar updates. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Webhooks & Notifications section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Webhooks & Notifications guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Webhooks & Notifications section cross-reference.

Module documentation hubs​

Pair with other Webhooks & Notifications guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen operator follow-up. Full pairing matrix: Webhooks & Notifications section cross-reference.

  • Inbox module — WhatsApp threads when webhook-driven imports generate tenant message notifications (hub)
  • Listings module — Property wizard, Channels tab, and unit management (hub)
  • Finance module — Portfolio ledgers with payment approval and deposit settlement (hub)
  • Tenants module — Tenant directory and profile sidebars for imported stays (hub)
  • Sales module — Portfolio availability and channel manager connections (hub)
  • Audit module — Portfolio-wide Manual Blocks and Discounts contract-value review (hub)
  • Dashboard module — Post-login KPI snapshot with bell notification triage (hub)
  • Analytics module — Month-range portfolio KPI charts with rankings and heatmaps (hub)
  • Properties workspace — Legacy /properties URL redirects into Listings (hub)
  • Booking engine details — Rich marketplace payload editor via the Full integration pill (hub)
  • Utilities module — Bills Included ceiling model and tenant overage charges (hub)
  • Operations module — Maintenance tickets, cash flows, and check-in/out coordination (hub)
  • Notifications module — Full /notifications history with search and filters (hub); Payment overdue alerts when webhook-driven imports leave unpaid schedules
  • AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)