Skip to main content

​
Webhooks API Reference Guide

This document provides a comprehensive guide for integrating with Monument webhooks. Webhooks allow you to receive real-time notifications about tenant lifecycle events in your Monument system.

​
Overview

Monument securely sends event notifications to your endpoints via webhooks. Webhooks enable you to stay synchronized with tenant activities such as move-ins, move-outs, rent changes, and more.

​
Authentication

Determining the expected signature Monument uses an HMAC with SHA-256 to sign its webhooks. So to calculate the expected signature, you should HMAC the signedcontent from above using the base64 portion of your signing secret (this is the part after the whsec prefix) as the key. For example, given the secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw you will want to use MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw. For example, this is how you can calculate the signature in Node.js: 
const crypto = require('crypto');

const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

// Need to base64 decode the secret
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
const signature = crypto
  .createHmac('sha256', secretBytes)
  .update(signedContent)
  .digest('base64');

console.log(signature);
This generated signature should match one of the ones sent in the svix-signature header. The svix-signature header is composed of a list of space delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one. Though there could be any number of signatures. For example: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo= Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature. Please note that to compare the signatures it’s recommended to use a constant-time string comparison method in order to prevent timing attacks.

​
Webhook Events

Monument publishes the following webhook events. Each event is triggered by specific actions within the Monument system. Response Body: All webhook events include a data key with an array base response structure with the following fields:
  • event (string): The event type (e.g., “moved-in”)
  • eventId (string): Unique event identifier in format {rentalRecordUuid}-{event_timestamp}-{event}
  • tenantUuid (UUID): Unique identifier for the tenant
  • unitRental (object): Contains rental information including:
    • rentalRecordUuid (UUID): Unique identifier for the rental record
    • unitGroupUuid (UUID): Unique identifier for the unit group
    • unitUuid (UUID): Unique identifier for the unit
    • facilityUuid (UUID): Unique identifier for the facility
    • rentalBalance (number): Current rental balance
    • startRentDate (string): Start date of the rental
    • endRentDate (string): End date of the rental
  • billingTemplate (object): Contains billing information including:
    • currentRentInPennies (number): Current rent amount in pennies
    • additionalServicesAndFees (array): Array of additional services and fees
    • promotions (array): Array of active promotions
    • billingDayOfMonth (number): Day of month when billing occurs
    • nextDueDate (string): Next payment due date
  • tenantBalanceInPennies (number): Total tenant balance in pennies
  • primaryContact (object): Contains primary contact information including:
    • firstName (string): First name
    • lastName (string): Last name
    • phone (string): Phone number
    • isSMSEnrolled (boolean): Whether SMS enrollment is active
    • email (string): Email address

​
1. moved-in

Event Type: moved-in Description: Triggered when a lead is successfully converted to a tenant on the Monument system. When This Event Fires:
  • A lead signs their lease and is converted to a tenant
Response Body: Uses the same base response structure.

​
2. moved-out

Event Type: moved-out Description: Triggered when a tenant moves out of their storage unit. When This Event Fires:
  • When a move-out request is processed and completed
Response Body: Uses the same base response structure.

​
3. rent-change

Event Type: rent-change Description: Triggered when the rent amount for a tenant’s unit changes. When This Event Fires:
  • When a rent modification is applied to an active rental
Response Body: Extends the base response structure with an additional rentChange object:
  • All base response fields
  • rentChange (object): Contains rent change details:
    • previousRentInPennies (number): Previous rent amount in pennies
    • currentRentInPennies (number): Current rent amount in pennies
    • rentChangeDate (string): Date when the rent change was made
    • rentChangeEffectiveDate (string): Date when the rent change becomes effective

​
4. delinquency-status-change

Event Type: delinquency-status-change Description: Triggered when a tenant’s delinquency status changes (e.g., from OVERDUE to OVERlOCK, or from OVERLOCK to PAID). When This Event Fires:
  • When a payment is missed and the account becomes overdue
  • When a payment is received that resolves delinquency
  • When delinquency stages progress (overdue → overlock → lien)
Response Body: Extends the base response structure with an additional delinquencyStatusChange object:
  • All base response fields
  • delinquencyStatusChange (object): Contains delinquency status change details:
    • delinquencyUuid (UUID): Unique identifier for the delinquency record
    • delinquencyPreviousStatus (string): Previous delinquency status (e.g., “OVERDUE”, “OVERLOCK”, “LIEN”, “AUCTION”, “PAID”, “PAUSED”, “WRITTEN_OFF”)
    • delinquencyNewStatus (string): New delinquency status
    • delinquencyStatusChangeDate (string): Date when the status change occurred
    • paymentDate (string | null): Date of payment if status change was due to payment

​
5. recurring-service-change

Event Type: recurring-service-change Description: Triggered when recurring services (additional services) are added to or removed from a tenant’s account. When This Event Fires:
  • When services are added during move-in or after move-in
  • When services are removed from an active rental
Response Body: Extends the base response structure with an additional recurringServiceChange object:
  • All base response fields
  • recurringServiceChange (object): Contains recurring service change details:
    • previousAdditionalServicesFees (array): Array of previous additional services and fees, each containing:
      • description (string): Service description
      • amount (number): Service amount
      • feeType (string): Fee type (e.g., “FIXED_AMOUNT”, “PERCENTAGE”)
      • itemTypeUuid (UUID): Unique identifier for the item type
    • currentAdditionalServicesFees (array): Array of current additional services and fees (same structure as above)
    • serviceChangeDate (string): Date when the service change was made
    • serviceChangeEffectiveDate (string): Date when the service change becomes effective

​
How to Subscribe to Webhook Events

To subscribe to webhook events, you can use the Monument API to create and manage webhook subscriptions programmatically.

​
Create Webhook Subscription

Creates a new webhook subscription for the specified application.

​
Endpoint

POST https://public-api.{env}.monument.io/api/v1/webhooks/subscriptions

​
Request Headers

x-api-key: YOUR_API_KEY

​
Request Body

{
  "vendorName": "example-vendor",
  "targetUrl": "https://vendor.example.com/webhooks/monument",
  "eventTypes": ["moved-in", "moved-out", "rent-change"],
  "description": "Webhook subscription for tenant lifecycle events",
  "portfolio": "portfolio-prefix",
  "facilityUuids": ["11111111-1111-1111-1111-111111111111"],
  "amenityUuids": ["22222222-2222-2222-2222-222222222222"],
  "unitTypes": ["33333333-3333-3333-3333-333333333333"]
}
Request Fields:
  • vendorName (string, required): Vendor name identifier
  • targetUrl (string, required): HTTPS URL where webhook events will be sent (must be HTTPS, no localhost, loopback, or private IPs, no query string)
  • eventTypes (array of strings, required): Array of event types to subscribe to (e.g., ["moved-in", "moved-out", "rent-change"])
  • description (string, required): Description of the webhook subscription
  • portfolio (string, required): Database prefix (portfolio identifier)
  • facilityUuids (array of UUIDs, optional): Filter events by specific facility UUIDs
  • amenityUuids (array of UUIDs, optional): Filter events by specific amenity UUIDs
  • unitTypes (array of UUIDs, optional): Filter events by specific unit type UUIDs

​
Response

{
  "endpointId": "ep_1234567890",
  "applicationId": "app_1234567890",
  "url": "https://vendor.example.com/webhooks/monument",
  "subscribedEventTypes": ["moved-in", "moved-out", "rent-change"],
  "facilityUuids": ["11111111-1111-1111-1111-111111111111"],
  "amenityUuids": ["22222222-2222-2222-2222-222222222222"],
  "unitTypes": ["33333333-3333-3333-3333-333333333333"],
  "databasePrefix": "portfolio-prefix",
  "secret": "whsec_****"
}
Response Fields:
  • endpointId (string): Svix endpoint ID
  • applicationId (string): Svix application ID
  • url (string): Webhook URL
  • subscribedEventTypes (array of strings): Event types that are subscribed
  • facilityUuids (array of UUIDs): Facility UUIDs filter
  • amenityUuids (array of UUIDs): Amenity UUIDs filter
  • unitTypes (array of UUIDs): Unit type UUIDs filter
  • databasePrefix (string): Database prefix
  • secret (string): Endpoint secret for webhook signature verification (store this securely)
Note: Save the secret value securely. You’ll need it to verify webhook signatures (see Authentication section).

​
Unsubscribe from Webhook Events

Unsubscribes from one or more event types. If all event types are unsubscribed, the endpoint may be removed.

​
Endpoint

DELETE https://public-api.{env}.monument.io/api/v1/webhooks/subscriptions

​
Request Headers

x-api-key: YOUR_API_KEY

​
Request Body

{
  "vendorName": "example-vendor",
  "portfolio": "portfolio-prefix",
  "eventTypes": ["moved-out"]
}
Request Fields:
  • vendorName (string, required): Vendor name identifier
  • portfolio (string, required): Database prefix (portfolio identifier)
  • eventTypes (array of strings, required): Array of event types to unsubscribe from

​
Response

{
  "applicationId": "app_1234567890",
  "vendorName": "example-vendor",
  "endpointId": "ep_1234567890",
  "url": "https://vendor.example.com/webhooks/monument",
  "unsubscribedEventTypes": ["moved-out"],
  "remainingEventTypes": ["moved-in", "rent-change"]
}
Response Fields:
  • applicationId (string): Svix application ID
  • vendorName (string): Vendor name
  • endpointId (string): Svix endpoint ID
  • url (string): Webhook URL
  • unsubscribedEventTypes (array of strings, optional): Event types that were unsubscribed (only present for partial unsubscribe)
  • remainingEventTypes (array of strings, optional): Event types that remain subscribed (only present for partial unsubscribe)

​
Webhook Configuration

Your webhook configuration can be customized to:
  • Filter events by facility UUIDs
  • Filter events by unit types
  • Filter events by amenities
  • Enable or disable specific event types
Note: If you need assistance setting up your webhook subscription or have questions about configuration, contact the Monument Integrations Team. Email: [email protected]

​
How to Manage Webhooks and Events

Monument provides API endpoints to manage your webhook subscriptions and access the webhook management dashboard.

​
Get Webhook Subscriptions

Retrieves all webhook subscriptions for the specified application. You can optionally filter by target URL or event type.

​
Endpoint

GET https://public-api.{env}.monument.io/api/v1/webhooks/subscriptions?targetUrl={url}&eventType={eventType}

​
Request Headers

x-api-key: YOUR_API_KEY

​
Query Parameters

  • targetUrl (string, optional): Filter subscriptions by target URL
  • eventType (string, optional): Filter subscriptions by event type

​
Response

{
  "applicationId": "app_1234567890",
  "items": [
    {
      "url": "https://vendor.example.com/webhooks/monument",
      "description": "Webhook subscription for tenant lifecycle events",
      "eventType": "moved-in",
      "facilityUuids": ["11111111-1111-1111-1111-111111111111"],
      "unitTypes": ["33333333-3333-3333-3333-333333333333"],
      "amenityUuids": ["22222222-2222-2222-2222-222222222222"],
      "portfolio": "portfolio-prefix"
    }
  ]
}
Response Fields:
  • applicationId (string): Svix application ID
  • items (array): Array of subscription items, each containing:
    • url (string): Webhook URL
    • description (string): Subscription description
    • eventType (string): Event type for this subscription
    • facilityUuids (array of UUIDs): Facility UUIDs filter
    • unitTypes (array of UUIDs): Unit type UUIDs filter
    • amenityUuids (array of UUIDs): Amenity UUIDs filter
    • portfolio (string): Database prefix
Retrieves a secure link to the webhook management dashboard where you can:
  • View webhook delivery status and history
  • View endpoint secrets for authentication
  • Monitor webhook delivery success and failure rates
  • Configure retry settings
  • View event logs

​
Endpoint

GET https://public-api.{env}.monument.io/api/v1/webhooks/dashboard-link

​
Request Headers

x-api-key: YOUR_API_KEY

​
Response

{
  "url": "https://portal.monument.io/webhooks/1234567890"
}
Response Fields:
  • url (string, required): Secure URL to the webhook management dashboard. This link expires after 7 days and a new link will need to be generated.
Note: The dashboard link provides read-only access to view webhook configuration and delivery status. For making changes to webhook subscriptions, use the subscription management endpoints or contact the integrations support team. Email: [email protected]

​
Send Test Event

Sends a test event to verify your webhook endpoint is working correctly.

​
Endpoint

POST https://public-api.{env}.monument.io/api/v1/webhooks/subscriptions/test

​
Request Headers

x-api-key: YOUR_API_KEY

​
Request Body

{
  "eventType": "moved-in"
}
Request Fields:
  • eventType (string, required): Event type to send as a test (e.g., “moved-in”, “moved-out”, “rent-change”)

​
Response

Returns HTTP 200 OK on success.

​
Best Practices

  1. Idempotency: Design your webhook handlers to be idempotent. Events may be delivered multiple times, so ensure processing the same event multiple times doesn’t cause issues. You will receive on your endpoint a header called webhook-id which is unique per message allowing you to handle deduplication on the receiving end as well, considering the at least once delivery policy.
  2. Quick Response: Respond to webhook requests quickly (within a few seconds). If processing takes longer, acknowledge the webhook and process asynchronously.
  3. Error Handling: Return appropriate HTTP status codes:
    • 2xx: Successfully received and processed
    • 4xx: Client error (your endpoint issue)
    • 5xx: Server error (temporary issue, will retry)
  4. Security: Always verify webhook signatures to ensure requests are from Monument (see Authentication section).
  5. Retry Handling: Monument will automatically retry failed deliveries. Ensure your endpoint can handle retry attempts gracefully. Failed deliveries are retried according to our retry policy. Ensure your endpoint can handle retry attempts. Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:
    • Immediately
    • 5 seconds
    • 5 minutes
    • 30 minutes
    • 2 hours
    • 5 hours
    • 10 hours
    • 10 hours (in addition to the previous)
    If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well. For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.
  6. Event Ordering: While events are generally delivered in order, design your system to handle out-of-order events if necessary. Monument also sends on every payload an eventId key composed of three parts {rentalRecordUuid}-{event_timestamp}-{event}, you can use it to properly order the event items.

​
Questions?

If you have questions about webhooks, need help setting up your integration, or require clarification on event behavior, please contact the Monument Integrations Support Team. Email: [email protected]