Webhooks
Webhooks tell your system the moment something happens in a Vlge community: a ticket is opened, an ARC request is decided, a payment clears or comes back, a bill is paid. Vlge sends a signed HTTPS POST with a small JSON body to each endpoint you register. Payloads carry ids, statuses, amounts in cents, and dates. They never include names, email addresses, message text, or bank details, so use the ids to look up anything else through the Organization API.
- Signing
- Standard Webhooks (HMAC-SHA256)
- API version
2026-11-09- Transport
- HTTPS only, public hosts only, no redirects followed
- Delivery
- At least once, retried for about 35 hours
Add an endpoint
Endpoints are set up here in the Developer Portal, under My Webhooks in your account menu. You need approved developer access and a role that can configure integrations in the community. Each endpoint belongs to one community; if a community is not listed, ask Vlge support to turn webhooks on for it.
- Choose Add destination and pick the events it should receive. Choose individual events, or a whole family such as
payment.*, which also picks up events added to that family later. When returned payments are included, a filter under the list can limitpayment.ach_returnedto specific return codes (for exampleR02,R10). Leave it empty to receive every return. - Press Continue, choose the community, give the destination a name, and enter an
https://URL. - Copy the signing secret. It starts with
whsec_and is shown once; rotate it from the destination page if it leaks. - Press Send test. Vlge sends a
webhook.pingso you can confirm your endpoint and signature check.
Each community can register up to 10 endpoints. The Event deliveries tab on each destination shows every attempt, the response code, and the request body, and lets you resend one.
Payload format
Every event has the same envelope. data differs by event type; the catalog below shows an example for each.
Request headers
POST /your/endpoint HTTP/1.1 Content-Type: application/json User-Agent: Vlge-Webhooks/1.0 webhook-id: evt_01JC8Z6T3W9V4K2M7Q5R1N0B8D webhook-timestamp: 1762700645 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Request body
{
"id": "evt_01JC8Z6T3W9V4K2M7Q5R1N0B8D",
"type": "ticket.status_changed",
"api_version": "2026-11-09",
"created_at": "2026-11-09T15:04:05.000Z",
"organization_id": "cmorg123",
"data": {
"ticket_id": "tkt_8f2c",
"status": "in_progress",
"category": "maintenance",
"property_id": "cmprop12",
"created_at": "2026-11-09T15:04:05.000Z",
"previous_status": "open"
}
}idis unique per event and matches thewebhook-idheader. Use it to discard duplicates.organization_idis the community the event belongs to, the same id the Organization API uses.- Amounts are integer cents (
amount_cents: 25000is $250.00). Dates without a time areYYYY-MM-DD. - New fields can be added to
dataat any time. Ignore fields you do not recognize.
Verify signatures
The webhook-signature header is v1, followed by the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded part of your secret after whsec_. Rotating the secret takes effect immediately, so update your server right after you rotate. The header format allows several space-separated signatures; accept the request if any one matches. Compute the signature over the raw request bytes, before any JSON parsing, and reject timestamps more than five minutes from now.
Node.js
import crypto from 'node:crypto';
// The signing secret from the Webhooks screen, e.g. "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw".
const secret = Buffer.from(process.env.VLGE_WEBHOOK_SECRET.replace(/^whsec_/, ''), 'base64');
export function verifyVlgeWebhook(rawBody, headers) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = String(headers['webhook-signature'] || '').split(' ');
// Reject anything older or newer than five minutes (replay protection).
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${id}.${timestamp}.${rawBody}`)
.digest('base64');
return signatures.some((entry) => {
const [version, signature] = entry.split(',');
return version === 'v1' && signature &&
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
});
}With a Standard Webhooks library
// Any Standard Webhooks library works, for example:
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.VLGE_WEBHOOK_SECRET.replace(/^whsec_/, ''));
const event = wh.verify(rawBody, headers); // throws if the signature is wrongSome receivers, such as automation tools, can only check a fixed key in a header. For those, add a custom header to the destination (for example Authorization: Bearer …). Vlge sends it on every delivery, alongside the signature headers. The value is stored encrypted and is not shown again after you save. Verifying the signature is still the stronger check when your receiver supports it.
Responding
- Return any
2xxstatus within 5 seconds. The response body is ignored. - Anything else, including a redirect, a timeout, or a TLS error, counts as a failure and is retried.
- Do slow work after you respond: store the event, return
200, and process it from a queue.
Retries and disabling
A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours. If the last retry also fails, the delivery is marked failed and the endpoint is turned off. The community's integration admins get an email, and you can turn the endpoint back on and resend from the delivery log.
After 5 failures in a row the endpoint is marked failing. Vlge then sends it one delivery at a time until it answers 2xx, so a recovering server is not flooded. A failed Send test never turns an endpoint off.
Duplicates and order
- Delivery is at least once. A network error after your server answered can cause a second delivery of the same event, and a manual resend always repeats it. Record each
idyou have processed and skip repeats. - Events are not guaranteed to arrive in order. Use
created_atand thestatusindata, or fetch the current record from the Organization API, rather than assuming the latest delivery is the latest state. - Bulk imports do not send one event per row. You get a single
import.completedinstead.
Limits
- Each community can receive up to 20,000 deliveries a day across all of its endpoints. Past that, new events are not queued until the next day, and the integration admins get one email.
- Send test and resend are limited to 10 a minute per community.
- Up to 10 endpoints per community.
Event catalog
Subscribe to individual events or to a family with family.*.
Communication · communication.*
Group email sent to or received by a community address.
- Show exampleHide example
communication.group_email_sentA group email was sent from a community address.
{ "message_id": "msg_61aa", "group_id": "grp_2b", "recipient_count": 140, "sent_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
communication.group_email_receivedAn email arrived at a community group address.
{ "message_id": "msg_61ab", "group_id": "grp_2b", "received_at": "2026-11-09T15:04:05.000Z" }
Tickets · ticket.*
Resident support tickets.
- Show exampleHide example
ticket.createdA resident or admin opened a ticket.
{ "ticket_id": "tkt_8f2c", "status": "open", "category": "maintenance", "property_id": "cmprop12", "created_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
ticket.commentedSomeone added a comment to a ticket.
{ "ticket_id": "tkt_8f2c", "status": "open", "category": "maintenance", "property_id": "cmprop12", "created_at": "2026-11-09T15:04:05.000Z", "comment_id": "cmt_09", "internal": false } - Show exampleHide example
ticket.status_changedA ticket moved to a new status.
{ "ticket_id": "tkt_8f2c", "status": "in_progress", "category": "maintenance", "property_id": "cmprop12", "created_at": "2026-11-09T15:04:05.000Z", "previous_status": "open" } - Show exampleHide example
ticket.withdrawnThe resident withdrew a ticket.
{ "ticket_id": "tkt_8f2c", "status": "withdrawn", "category": "maintenance", "property_id": "cmprop12", "created_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
ticket.reopenedA closed ticket was reopened.
{ "ticket_id": "tkt_8f2c", "status": "open", "category": "maintenance", "property_id": "cmprop12", "created_at": "2026-11-09T15:04:05.000Z", "previous_status": "closed" }
ARC requests · acc.*
Architectural review submissions, comments, votes, and decisions.
- Show exampleHide example
acc.submittedA resident submitted an ARC request.
{ "request_id": "acc_31d0", "status": "submitted", "property_id": "cmprop12", "submitted_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
acc.commentedSomeone commented on an ARC request.
{ "request_id": "acc_31d0", "status": "under_review", "property_id": "cmprop12", "submitted_at": "2026-11-09T15:04:05.000Z", "comment_id": "cmt_10" } - Show exampleHide example
acc.status_changedAn ARC request moved to a new status.
{ "request_id": "acc_31d0", "status": "under_review", "property_id": "cmprop12", "submitted_at": "2026-11-09T15:04:05.000Z", "previous_status": "submitted" } - Show exampleHide example
acc.vote_castA reviewer voted on an ARC request. The vote itself is not included.
{ "request_id": "acc_31d0", "status": "under_review", "property_id": "cmprop12", "submitted_at": "2026-11-09T15:04:05.000Z", "vote_count": 2 } - Show exampleHide example
acc.finalizedA decision was recorded on an ARC request.
{ "request_id": "acc_31d0", "status": "approved", "property_id": "cmprop12", "submitted_at": "2026-11-09T15:04:05.000Z", "decided_at": "2026-11-12T18:00:00.000Z" }
Violations · violation.*
Violation cases, notices, and resident responses.
- Show exampleHide example
violation.createdA violation case was opened.
{ "violation_id": "vio_77aa", "status": "draft", "property_id": "cmprop12", "category": "landscaping" } - Show exampleHide example
violation.issuedA violation notice was issued to the owner.
{ "violation_id": "vio_77aa", "status": "issued", "property_id": "cmprop12", "category": "landscaping" } - Show exampleHide example
violation.commentedSomeone commented on a violation.
{ "violation_id": "vio_77aa", "status": "issued", "property_id": "cmprop12", "category": "landscaping", "comment_id": "cmt_11" } - Show exampleHide example
violation.resident_respondedThe owner responded to a violation.
{ "violation_id": "vio_77aa", "status": "issued", "property_id": "cmprop12", "category": "landscaping", "response_id": "rsp_3" }
Access requests · access.*
People asking to join the community and the decision.
- Show exampleHide example
access.requestedSomeone asked to join the community.
{ "request_id": "arq_5b1e", "status": "pending", "property_id": "cmprop12" } - Show exampleHide example
access.approvedAn access request was approved.
{ "request_id": "arq_5b1e", "status": "approved", "property_id": "cmprop12", "user_id": "cmuser4" } - Show exampleHide example
access.deniedAn access request was denied.
{ "request_id": "arq_5b1e", "status": "denied", "property_id": "cmprop12" } - Show exampleHide example
access.signup_completedAn approved person finished creating their account.
{ "request_id": "arq_5b1e", "status": "completed", "property_id": "cmprop12", "user_id": "cmuser4" }
Quick votes · quick_vote.*
Board and committee quick votes opening and closing.
- Show exampleHide example
quick_vote.openedA quick vote was opened and voters were emailed. Fetch it with the connector for questions and turnout.
{ "quick_vote_id": "qv_6c1d", "status": "open", "kind": "formal", "opens_at": "2026-11-09T15:00:00.000Z", "closes_at": "2026-11-12T23:00:00.000Z", "voter_count": 5, "submitted_count": 0 } - Show exampleHide example
quick_vote.closedA quick vote closed: by an admin, at its close time, or when everyone had voted.
{ "quick_vote_id": "qv_6c1d", "status": "closed", "kind": "formal", "opens_at": "2026-11-09T15:00:00.000Z", "closes_at": "2026-11-12T23:00:00.000Z", "voter_count": 5, "submitted_count": 5 }
Motions · motion.*
Board motions closing and recording a result.
- Show exampleHide example
motion.vote_closedA board motion closed and its result was recorded.
{ "motion_id": "cmmotion1", "status": "closed", "outcome": "carried", "yes_count": 4, "seat_count": 5 }
Payments · payment.*
Resident payments, returns, disputes, and refunds.
- Show exampleHide example
payment.succeededA payment cleared and was applied to the account.
{ "payment_id": "pay_19cd", "status": "succeeded", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
payment.processingA payment was accepted and is waiting to clear.
{ "payment_id": "pay_19cd", "status": "processing", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
payment.action_requiredA payment needs the payer to take another step.
{ "payment_id": "pay_19cd", "status": "action_required", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
payment.canceledA payment was canceled before it cleared.
{ "payment_id": "pay_19cd", "status": "canceled", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z" } - Show exampleHide example
payment.card_declinedA card payment was declined.
{ "payment_id": "pay_19cd", "status": "failed", "amount_cents": 25000, "method": "card", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "decline_code": "insufficient_funds" } - Show exampleHide example
payment.ach_insufficient_fundsA bank payment failed for insufficient funds.
{ "payment_id": "pay_19cd", "status": "failed", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "return_code": "R01" } - Show exampleHide example
payment.ach_returnedA bank payment was returned. Filter by return_code on the endpoint.
{ "payment_id": "pay_19cd", "status": "returned", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "return_code": "R02" } - Show exampleHide example
payment.ach_notice_of_changeThe payer’s bank sent corrected account details.
{ "payment_id": "pay_19cd", "status": "succeeded", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "change_code": "C01" } - Show exampleHide example
payment.autopay_failedAn autopay attempt failed.
{ "payment_id": "pay_19cd", "status": "failed", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "autopay_id": "ap_7" } - Show exampleHide example
payment.autopay_suspendedAutopay was turned off after repeated failures.
{ "autopay_id": "ap_7", "property_id": "cmprop12", "status": "suspended" } - Show exampleHide example
payment.check_depositedA mailed check was deposited.
{ "payment_id": "pay_19cd", "status": "succeeded", "amount_cents": 25000, "method": "check", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "check_number": "1042" } - Show exampleHide example
payment.dispute_openedThe payer disputed a payment with their bank.
{ "payment_id": "pay_19cd", "status": "disputed", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "dispute_id": "dp_1" } - Show exampleHide example
payment.dispute_funds_withdrawnDisputed funds were taken back from the community.
{ "payment_id": "pay_19cd", "status": "succeeded", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "dispute_id": "dp_1" } - Show exampleHide example
payment.dispute_funds_reinstatedDisputed funds were returned to the community.
{ "payment_id": "pay_19cd", "status": "succeeded", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "dispute_id": "dp_1" } - Show exampleHide example
payment.dispute_closedA dispute was resolved.
{ "payment_id": "pay_19cd", "status": "succeeded", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "dispute_id": "dp_1", "outcome": "won" } - Show exampleHide example
payment.refund_requestedA refund was requested.
{ "payment_id": "pay_19cd", "status": "requested", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "refund_id": "rf_2" } - Show exampleHide example
payment.refund_approvedA refund was approved.
{ "payment_id": "pay_19cd", "status": "approved", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "refund_id": "rf_2" } - Show exampleHide example
payment.refund_rejectedA refund request was rejected.
{ "payment_id": "pay_19cd", "status": "rejected", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "refund_id": "rf_2" } - Show exampleHide example
payment.refund_succeededA refund was sent to the payer.
{ "payment_id": "pay_19cd", "status": "succeeded", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "refund_id": "rf_2" } - Show exampleHide example
payment.refund_failedA refund could not be sent.
{ "payment_id": "pay_19cd", "status": "failed", "amount_cents": 25000, "method": "ach", "property_id": "cmprop12", "occurred_at": "2026-11-09T15:04:05.000Z", "refund_id": "rf_2" } - Show exampleHide example
payment.returned_fee_postedA returned-payment fee was charged to the account.
{ "charge_id": "chg_5", "property_id": "cmprop12", "amount_cents": 3500 }
Banking · bank.*
Statements and transfers on the community operating account.
- Show exampleHide example
bank.statement_availableA new bank statement is ready.
{ "statement_id": "stm_9", "account_id": "cmacct3", "statement_date": "2026-10-31" } - Show exampleHide example
bank.transfer_requestedSomeone requested a transfer.
{ "transfer_id": "trf_4410", "status": "requested", "amount_cents": 500000, "direction": "outgoing" } - Show exampleHide example
bank.transfer_approvedA transfer was approved.
{ "transfer_id": "trf_4410", "status": "approved", "amount_cents": 500000, "direction": "outgoing" } - Show exampleHide example
bank.transfer_rejectedA transfer was rejected.
{ "transfer_id": "trf_4410", "status": "rejected", "amount_cents": 500000, "direction": "outgoing" } - Show exampleHide example
bank.transfer_submittedAn approved transfer was sent to the bank.
{ "transfer_id": "trf_4410", "status": "submitted", "amount_cents": 500000, "direction": "outgoing" } - Show exampleHide example
bank.transfer_settledA transfer to or from an outside account settled.
{ "transfer_id": "trf_4410", "status": "settled", "amount_cents": 500000, "direction": "outgoing" } - Show exampleHide example
bank.transfer_returnedA transfer to or from an outside account was returned.
{ "transfer_id": "trf_4410", "status": "returned", "amount_cents": 500000, "direction": "outgoing", "return_code": "R03" } - Show exampleHide example
bank.transfer_withdrawnA transfer request was withdrawn before approval.
{ "transfer_id": "trf_4410", "status": "withdrawn", "amount_cents": 500000, "direction": "outgoing" }
Payouts · payout.*
Card and ACH funds paid out to the community bank account.
- Show exampleHide example
payout.paidFunds arrived in the community bank account.
{ "payout_id": "po_0c92", "status": "paid", "amount_cents": 1240000, "arrival_date": "2026-11-10" } - Show exampleHide example
payout.failedA payout could not be delivered.
{ "payout_id": "po_0c92", "status": "failed", "amount_cents": 1240000, "arrival_date": "2026-11-10" }
Bills · bill.*
Vendor bills received, approved, and paid.
- Show exampleHide example
bill.receivedA vendor bill was received.
{ "bill_id": "bil_2a7f", "status": "received", "amount_cents": 87500, "vendor_id": "cmvend9", "due_date": "2026-11-30" } - Show exampleHide example
bill.approvedA bill was approved for payment.
{ "bill_id": "bil_2a7f", "status": "approved", "amount_cents": 87500, "vendor_id": "cmvend9", "due_date": "2026-11-30" } - Show exampleHide example
bill.rejectedA bill was rejected.
{ "bill_id": "bil_2a7f", "status": "rejected", "amount_cents": 87500, "vendor_id": "cmvend9", "due_date": "2026-11-30" } - Show exampleHide example
bill.paidA bill was paid.
{ "bill_id": "bil_2a7f", "status": "paid", "amount_cents": 87500, "vendor_id": "cmvend9", "due_date": "2026-11-30", "paid_at": "2026-11-20T12:00:00.000Z" } - Show exampleHide example
bill.voidedA bill or its payment was voided.
{ "bill_id": "bil_2a7f", "status": "voided", "amount_cents": 87500, "vendor_id": "cmvend9", "due_date": "2026-11-30" }
Imports · import.*
Bulk data imports.
- Show exampleHide example
import.completedA bulk import finished. Per-row events are not sent for imports.
{ "import_type": "properties", "created_count": 412, "updated_count": 18 }
Webhooks · webhook.*
Messages about the webhook endpoint itself.
- Show exampleHide example
webhook.pingalways sentSent when you click Send test. Safe to ignore.
{ "endpoint_id": "cmendpt1", "message": "Hello from Vlge." }
