Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/appfolio-webhooks-events/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill appfolio-webhooks-events. Copyright stays with the author (MIT).

AppFolio Webhooks & Events

Overview

AppFolio Stack delivers real-time webhook notifications for property management lifecycle events including tenant onboarding, lease execution, rent payments, and maintenance workflows. Use these webhooks to sync AppFolio data with your CRM, accounting system, or custom property management dashboards without polling the API.

Prerequisites

• Written confirmation in the current AppFolio partner contract that the target portfolio supports the event types, registration process, delivery semantics, and signature scheme. Do not infer webhook support from another integration.
• A bounded raw-body ingress route, managed webhook secret, durable event store, queue, idempotency table, and owner for downstream accounting/CRM effects.
• A sandbox endpoint and synthetic events for valid, malformed, duplicate, and delayed-delivery tests before production registration.

Instructions

1. Register events only through the provider-issued process and contract-bound client after verifying the target URL, allowlist, and secret delivery path.
2. Verify bounded raw bytes and the signature before parsing; reject malformed or replayed events without logging tenant, payment, or lease content.
3. Persist the event ID, type, received time, and encrypted/minimized payload transactionally before acknowledging delivery, then process it asynchronously.
4. Enforce durable idempotency and reconcile unknown downstream outcomes before writing CRM, accounting, tenant, lease, or work-order state.

Webhook Registration

// Use this only if the signed provider contract explicitly supports this API.
const response = await createVerifiedAppFolioClient().post("/webhooks", {
    url: "https://yourapp.com/webhooks/appfolio",
    events: ["tenant.created", "work_order.updated", "payment.received", "lease.signed"],
    secret: process.env.APPFOLIO_WEBHOOK_SECRET,
});

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyAppFolioSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-appfolio-signature"] as string;
  const expected = Buffer.from(crypto
    .createHmac("sha256", process.env.APPFOLIO_WEBHOOK_SECRET!)
    .update(req.body)
    .digest("hex"));
  const received = signature ? Buffer.from(signature) : Buffer.alloc(0);
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  next();
}

Event Handler

import express from "express";
const app = express();

app.post("/webhooks/appfolio", express.raw({ type: "application/json" }), verifyAppFolioSignature, (req, res) => {
  const event = JSON.parse(req.body.toString());
  // persistIncomingEvent performs a durable idempotency insert and queue write
  // in one transaction. A failed persist must receive a retryable response.
  persistIncomingEvent(event).then(() => {
    res.status(202).json({ received: true });
  }).catch(() => {
    res.status(503).json({ error: "Event persistence unavailable" });
  });
});

Event Types

Retry & Idempotency

async function handleIdempotent(event: { id: string; type: string; data: any }) {
  if (await durableEventStore.hasSucceeded(event.id)) return;
  await routeEvent(event);
  await durableEventStore.markSucceeded(event.id);
}

Error Handling

Output

• A contract-gated webhook registration decision and a fail-closed raw-body signature verification result
• A durable receipt for each accepted event before acknowledgement, with minimized/encrypted content and durable idempotency state
• A controlled asynchronous processing outcome that can be retried or reconciled without duplicate tenant, lease, payment, or work-order effects

Examples

For a synthetic work-order update, deliver a valid signed event, a malformed signature, a duplicate ID, and a downstream timeout. Prove the valid event is persisted before 202, the malformed request is rejected without parsing, the duplicate does not produce a second side effect, and the timeout remains queued for reconciliation. If provider support, raw-body capture, signature secret, durable store, or queue is unavailable, keep the endpoint disabled and use the provider-approved polling/reconciliation path instead.

Resources

• AppFolio Stack APIs

Next Steps

See appfolio-security-basics.