Skip to main content

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.

  1. 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 limit payment.ach_returned to specific return codes (for example R02, R10). Leave it empty to receive every return.
  2. Press Continue, choose the community, give the destination a name, and enter an https:// URL.
  3. Copy the signing secret. It starts with whsec_ and is shown once; rotate it from the destination page if it leaks.
  4. Press Send test. Vlge sends a webhook.ping so 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"
  }
}
  • id is unique per event and matches the webhook-id header. Use it to discard duplicates.
  • organization_id is the community the event belongs to, the same id the Organization API uses.
  • Amounts are integer cents (amount_cents: 25000 is $250.00). Dates without a time are YYYY-MM-DD.
  • New fields can be added to data at 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 wrong

Some 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 2xx status 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 id you have processed and skip repeats.
  • Events are not guaranteed to arrive in order. Use created_at and the status in data, 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.completed instead.

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.

  • communication.group_email_sent

    A group email was sent from a community address.

    Show example
    {
      "message_id": "msg_61aa",
      "group_id": "grp_2b",
      "recipient_count": 140,
      "sent_at": "2026-11-09T15:04:05.000Z"
    }
  • communication.group_email_received

    An email arrived at a community group address.

    Show example
    {
      "message_id": "msg_61ab",
      "group_id": "grp_2b",
      "received_at": "2026-11-09T15:04:05.000Z"
    }

Tickets · ticket.*

Resident support tickets.

  • ticket.created

    A resident or admin opened a ticket.

    Show example
    {
      "ticket_id": "tkt_8f2c",
      "status": "open",
      "category": "maintenance",
      "property_id": "cmprop12",
      "created_at": "2026-11-09T15:04:05.000Z"
    }
  • ticket.commented

    Someone added a comment to a ticket.

    Show example
    {
      "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
    }
  • ticket.status_changed

    A ticket moved to a new status.

    Show example
    {
      "ticket_id": "tkt_8f2c",
      "status": "in_progress",
      "category": "maintenance",
      "property_id": "cmprop12",
      "created_at": "2026-11-09T15:04:05.000Z",
      "previous_status": "open"
    }
  • ticket.withdrawn

    The resident withdrew a ticket.

    Show example
    {
      "ticket_id": "tkt_8f2c",
      "status": "withdrawn",
      "category": "maintenance",
      "property_id": "cmprop12",
      "created_at": "2026-11-09T15:04:05.000Z"
    }
  • ticket.reopened

    A closed ticket was reopened.

    Show example
    {
      "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.

  • acc.submitted

    A resident submitted an ARC request.

    Show example
    {
      "request_id": "acc_31d0",
      "status": "submitted",
      "property_id": "cmprop12",
      "submitted_at": "2026-11-09T15:04:05.000Z"
    }
  • acc.commented

    Someone commented on an ARC request.

    Show example
    {
      "request_id": "acc_31d0",
      "status": "under_review",
      "property_id": "cmprop12",
      "submitted_at": "2026-11-09T15:04:05.000Z",
      "comment_id": "cmt_10"
    }
  • acc.status_changed

    An ARC request moved to a new status.

    Show example
    {
      "request_id": "acc_31d0",
      "status": "under_review",
      "property_id": "cmprop12",
      "submitted_at": "2026-11-09T15:04:05.000Z",
      "previous_status": "submitted"
    }
  • acc.vote_cast

    A reviewer voted on an ARC request. The vote itself is not included.

    Show example
    {
      "request_id": "acc_31d0",
      "status": "under_review",
      "property_id": "cmprop12",
      "submitted_at": "2026-11-09T15:04:05.000Z",
      "vote_count": 2
    }
  • acc.finalized

    A decision was recorded on an ARC request.

    Show example
    {
      "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.

  • violation.created

    A violation case was opened.

    Show example
    {
      "violation_id": "vio_77aa",
      "status": "draft",
      "property_id": "cmprop12",
      "category": "landscaping"
    }
  • violation.issued

    A violation notice was issued to the owner.

    Show example
    {
      "violation_id": "vio_77aa",
      "status": "issued",
      "property_id": "cmprop12",
      "category": "landscaping"
    }
  • violation.commented

    Someone commented on a violation.

    Show example
    {
      "violation_id": "vio_77aa",
      "status": "issued",
      "property_id": "cmprop12",
      "category": "landscaping",
      "comment_id": "cmt_11"
    }
  • violation.resident_responded

    The owner responded to a violation.

    Show example
    {
      "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.

  • access.requested

    Someone asked to join the community.

    Show example
    {
      "request_id": "arq_5b1e",
      "status": "pending",
      "property_id": "cmprop12"
    }
  • access.approved

    An access request was approved.

    Show example
    {
      "request_id": "arq_5b1e",
      "status": "approved",
      "property_id": "cmprop12",
      "user_id": "cmuser4"
    }
  • access.denied

    An access request was denied.

    Show example
    {
      "request_id": "arq_5b1e",
      "status": "denied",
      "property_id": "cmprop12"
    }
  • access.signup_completed

    An approved person finished creating their account.

    Show example
    {
      "request_id": "arq_5b1e",
      "status": "completed",
      "property_id": "cmprop12",
      "user_id": "cmuser4"
    }

Quick votes · quick_vote.*

Board and committee quick votes opening and closing.

  • quick_vote.opened

    A quick vote was opened and voters were emailed. Fetch it with the connector for questions and turnout.

    Show example
    {
      "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
    }
  • quick_vote.closed

    A quick vote closed: by an admin, at its close time, or when everyone had voted.

    Show example
    {
      "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.

  • motion.vote_closed

    A board motion closed and its result was recorded.

    Show example
    {
      "motion_id": "cmmotion1",
      "status": "closed",
      "outcome": "carried",
      "yes_count": 4,
      "seat_count": 5
    }

Payments · payment.*

Resident payments, returns, disputes, and refunds.

  • payment.succeeded

    A payment cleared and was applied to the account.

    Show example
    {
      "payment_id": "pay_19cd",
      "status": "succeeded",
      "amount_cents": 25000,
      "method": "ach",
      "property_id": "cmprop12",
      "occurred_at": "2026-11-09T15:04:05.000Z"
    }
  • payment.processing

    A payment was accepted and is waiting to clear.

    Show example
    {
      "payment_id": "pay_19cd",
      "status": "processing",
      "amount_cents": 25000,
      "method": "ach",
      "property_id": "cmprop12",
      "occurred_at": "2026-11-09T15:04:05.000Z"
    }
  • payment.action_required

    A payment needs the payer to take another step.

    Show example
    {
      "payment_id": "pay_19cd",
      "status": "action_required",
      "amount_cents": 25000,
      "method": "ach",
      "property_id": "cmprop12",
      "occurred_at": "2026-11-09T15:04:05.000Z"
    }
  • payment.canceled

    A payment was canceled before it cleared.

    Show example
    {
      "payment_id": "pay_19cd",
      "status": "canceled",
      "amount_cents": 25000,
      "method": "ach",
      "property_id": "cmprop12",
      "occurred_at": "2026-11-09T15:04:05.000Z"
    }
  • payment.card_declined

    A card payment was declined.

    Show example
    {
      "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"
    }
  • payment.ach_insufficient_funds

    A bank payment failed for insufficient funds.

    Show example
    {
      "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"
    }
  • payment.ach_returned

    A bank payment was returned. Filter by return_code on the endpoint.

    Show example
    {
      "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"
    }
  • payment.ach_notice_of_change

    The payer’s bank sent corrected account details.

    Show example
    {
      "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"
    }
  • payment.autopay_failed

    An autopay attempt failed.

    Show example
    {
      "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"
    }
  • payment.autopay_suspended

    Autopay was turned off after repeated failures.

    Show example
    {
      "autopay_id": "ap_7",
      "property_id": "cmprop12",
      "status": "suspended"
    }
  • payment.check_deposited

    A mailed check was deposited.

    Show example
    {
      "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"
    }
  • payment.dispute_opened

    The payer disputed a payment with their bank.

    Show example
    {
      "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"
    }
  • payment.dispute_funds_withdrawn

    Disputed funds were taken back from the community.

    Show example
    {
      "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"
    }
  • payment.dispute_funds_reinstated

    Disputed funds were returned to the community.

    Show example
    {
      "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"
    }
  • payment.dispute_closed

    A dispute was resolved.

    Show example
    {
      "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"
    }
  • payment.refund_requested

    A refund was requested.

    Show example
    {
      "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"
    }
  • payment.refund_approved

    A refund was approved.

    Show example
    {
      "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"
    }
  • payment.refund_rejected

    A refund request was rejected.

    Show example
    {
      "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"
    }
  • payment.refund_succeeded

    A refund was sent to the payer.

    Show example
    {
      "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"
    }
  • payment.refund_failed

    A refund could not be sent.

    Show example
    {
      "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"
    }
  • payment.returned_fee_posted

    A returned-payment fee was charged to the account.

    Show example
    {
      "charge_id": "chg_5",
      "property_id": "cmprop12",
      "amount_cents": 3500
    }

Banking · bank.*

Statements and transfers on the community operating account.

  • bank.statement_available

    A new bank statement is ready.

    Show example
    {
      "statement_id": "stm_9",
      "account_id": "cmacct3",
      "statement_date": "2026-10-31"
    }
  • bank.transfer_requested

    Someone requested a transfer.

    Show example
    {
      "transfer_id": "trf_4410",
      "status": "requested",
      "amount_cents": 500000,
      "direction": "outgoing"
    }
  • bank.transfer_approved

    A transfer was approved.

    Show example
    {
      "transfer_id": "trf_4410",
      "status": "approved",
      "amount_cents": 500000,
      "direction": "outgoing"
    }
  • bank.transfer_rejected

    A transfer was rejected.

    Show example
    {
      "transfer_id": "trf_4410",
      "status": "rejected",
      "amount_cents": 500000,
      "direction": "outgoing"
    }
  • bank.transfer_submitted

    An approved transfer was sent to the bank.

    Show example
    {
      "transfer_id": "trf_4410",
      "status": "submitted",
      "amount_cents": 500000,
      "direction": "outgoing"
    }
  • bank.transfer_settled

    A transfer to or from an outside account settled.

    Show example
    {
      "transfer_id": "trf_4410",
      "status": "settled",
      "amount_cents": 500000,
      "direction": "outgoing"
    }
  • bank.transfer_returned

    A transfer to or from an outside account was returned.

    Show example
    {
      "transfer_id": "trf_4410",
      "status": "returned",
      "amount_cents": 500000,
      "direction": "outgoing",
      "return_code": "R03"
    }
  • bank.transfer_withdrawn

    A transfer request was withdrawn before approval.

    Show example
    {
      "transfer_id": "trf_4410",
      "status": "withdrawn",
      "amount_cents": 500000,
      "direction": "outgoing"
    }

Payouts · payout.*

Card and ACH funds paid out to the community bank account.

  • payout.paid

    Funds arrived in the community bank account.

    Show example
    {
      "payout_id": "po_0c92",
      "status": "paid",
      "amount_cents": 1240000,
      "arrival_date": "2026-11-10"
    }
  • payout.failed

    A payout could not be delivered.

    Show example
    {
      "payout_id": "po_0c92",
      "status": "failed",
      "amount_cents": 1240000,
      "arrival_date": "2026-11-10"
    }

Bills · bill.*

Vendor bills received, approved, and paid.

  • bill.received

    A vendor bill was received.

    Show example
    {
      "bill_id": "bil_2a7f",
      "status": "received",
      "amount_cents": 87500,
      "vendor_id": "cmvend9",
      "due_date": "2026-11-30"
    }
  • bill.approved

    A bill was approved for payment.

    Show example
    {
      "bill_id": "bil_2a7f",
      "status": "approved",
      "amount_cents": 87500,
      "vendor_id": "cmvend9",
      "due_date": "2026-11-30"
    }
  • bill.rejected

    A bill was rejected.

    Show example
    {
      "bill_id": "bil_2a7f",
      "status": "rejected",
      "amount_cents": 87500,
      "vendor_id": "cmvend9",
      "due_date": "2026-11-30"
    }
  • bill.paid

    A bill was paid.

    Show example
    {
      "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"
    }
  • bill.voided

    A bill or its payment was voided.

    Show example
    {
      "bill_id": "bil_2a7f",
      "status": "voided",
      "amount_cents": 87500,
      "vendor_id": "cmvend9",
      "due_date": "2026-11-30"
    }

Imports · import.*

Bulk data imports.

  • import.completed

    A bulk import finished. Per-row events are not sent for imports.

    Show example
    {
      "import_type": "properties",
      "created_count": 412,
      "updated_count": 18
    }

Webhooks · webhook.*

Messages about the webhook endpoint itself.

  • webhook.pingalways sent

    Sent when you click Send test. Safe to ignore.

    Show example
    {
      "endpoint_id": "cmendpt1",
      "message": "Hello from Vlge."
    }
Webhooks — Vlge Developer Portal | Vlge