Webhooks

    Real-time events across the lead-to-payment lifecycle

    Subscribe to signed webhook events so your systems react the moment something changes in URBLD — leads, jobs, invoices, and workflow state, delivered live.

    How do URBLD webhooks work?

    Register an HTTPS endpoint and select the events you want to receive. URBLD POSTs a JSON payload for every event with an HMAC-SHA256 signature in the X-URBLD-Signature header. Verify the signature, respond with 2xx within 10 seconds, and URBLD marks the delivery successful. Failed deliveries retry with exponential backoff for 24 hours.

    Payload format

    POST https://your-app.example.com/webhooks/urbld
    {
  "id": "evt_01HXYZ...",
  "type": "job.completed",
  "created_at": "2026-07-04T15:32:11Z",
  "org_id": "org_01HABCDE",
  "data": {
    "job_id": "job_01HXYZ",
    "lifecycle_number": "L-1042",
    "customer_id": "cus_01HXYZ",
    "completed_at": "2026-07-04T15:32:00Z"
  }
}

    Verifying signatures

    verify.ts
    import crypto from "node:crypto";

export function verifyUrbldWebhook(rawBody: string, signature: string, secret: string) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

    Available events

    EventFired when
    lead.createdA new lead was captured (form, phone, chat, or agent).
    lead.qualifiedA lead was qualified and ready for scheduling.
    appointment.bookedAn appointment was booked on the calendar.
    appointment.rescheduledAn appointment moved to a new time.
    appointment.cancelledAn appointment was cancelled.
    estimate.sentAn estimate was delivered to a customer.
    estimate.approvedA customer approved an estimate.
    contract.signedAll parties signed a contract package.
    job.createdA signed contract was converted to a job.
    job.completedA job reached completed state.
    invoice.issuedAn invoice was issued.
    invoice.paidAn invoice was fully paid.
    payment.receivedA payment was captured.
    message.receivedAn inbound SMS or email arrived in the unified inbox.

    Best practices

    • Respond with a 2xx status within 10 seconds. Do heavy work asynchronously.
    • Store the id and treat repeated deliveries as idempotent.
    • Verify signatures on every request — never trust the payload alone.
    • Use a dedicated URL per environment (staging, production) so replayed events do not cross environments.
    FAQ

    Frequently Asked Questions

    Straight answers about how URBLD runs the business end-to-end.