Skip to content
For developers

Webhooks

Event-driven integration: catalog, signatures, retries.

Last updated

Webhooks turn your integration from pull to push. Instead of polling the API on a schedule and diffing results, you register a URL once and ActuallyCare sends an HTTP POST to it the moment something happens. This page covers the concepts — event catalog, payload, signatures, delivery. For a step-by-step walkthrough, see the webhook setup guide.

Webhooks or polling?#

SituationBetter fit
React to changes as they happen (new lead, escrow update)Webhooks
Periodic full sync or reporting snapshotPolling the REST API
You can't host a public HTTPS endpointPolling
Low latency matters (lead routing, notifications)Webhooks

The usual pattern is both: webhooks for the real-time signal, with an occasional polled reconciliation pass as a safety net.

The event catalog#

The catalog is self-documenting. Ask the API what events exist (all /v1/webhooks endpoints take a JWT bearer token — not an API key — and need a broker or system-admin role, see Managing webhooks):

curl "https://api.actuallycare.com/v1/webhooks/events" \
  -H "Authorization: Bearer YOUR_JWT"

The response uses the standard envelope: data lists every event type with its category, description, and a list of key fields, and meta totals it up. The delivered record usually has more fields than that list, and some events use different field names, so read fields defensively. Add ?category=<name> to get one category. Trimmed to two entries:

{
  "success": true,
  "data": [
    {
      "event": "escrow.created",
      "category": "escrow",
      "description": "An escrow/transaction was created",
      "payload": ["id", "status", "property_address", "escrow_number"]
    },
    {
      "event": "lead.created",
      "category": "lead",
      "description": "A new lead was created",
      "payload": ["id", "name", "email", "phone", "source", "status"]
    }
  ],
  "meta": {
    "total": 150,
    "categories": ["appointment", "care_status", "client", "..."]
  }
}

The catalog covers every event name you can subscribe to — escrow.*, lead.*, client.*, listing.*, appointment.*, care_status.*, and more. Today, deliveries are sent for escrow, lead, client, listing, appointment, showing feedback, inventory, and care status events; other catalog events don't fire yet. A few representative examples:

EventFires when
escrow.createdA new escrow is opened
escrow.updatedAn escrow's details change
lead.createdA new lead enters the pipeline
lead.status_changedA lead's status changes
client.createdA new client relationship is created
listing.updatedA listing's details change
appointment.status_changedAn appointment's status changes (including cancellations)
care_status.changedA relationship's follow-up health changes

This table is illustrative — the catalog endpoint is the source of truth. GET /v1/webhooks/events/categories returns the category list if you want to browse by group. When you create a webhook you subscribe it to specific events, or to all of them. Event names aren't checked when you register, so a misspelled name is accepted and simply never fires — copy names from the catalog.

The payload envelope#

Every delivery is a POST with a JSON body in the same envelope:

{
  "event": "escrow.created",
  "team_id": "3f8a1c2e-9d4b-4f6a-8e2d-1b7c5a9e0f3d",
  "timestamp": "2026-06-11T17:32:08.123Z",
  "data": {
    "id": "9c4e7b1a-2f8d-4e3c-a6b5-0d1f2e3a4b5c"
  }
}
FieldMeaning
eventThe event type that fired
team_idThe team the event belongs to, or null when the record has no team
timestampWhen the event occurred
dataThe affected record — its shape depends on the event type

Verifying signatures#

Every delivery is signed so you can confirm it really came from ActuallyCare. Three headers arrive with each request:

HeaderContents
X-Webhook-Signaturesha256= followed by the HMAC-SHA256 hex digest of the JSON body, computed with your webhook secret (e.g. sha256=3f5a…).
X-Webhook-EventThe event type, same as event in the body
X-Webhook-TimestampThe same value as timestamp in the body. It's set when the event is first sent and stays the same on retries

Compute the same HMAC over the raw request body and compare with a timing-safe comparison — never a plain string equality:

const crypto = require('crypto');
const express = require('express');
 
const app = express();
 
function verifySignature(rawBody, signatureHeader, secret) {
  const expectedHex = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
 
  // Header format: "sha256=<hex digest>"
  const receivedHex = (signatureHeader || '').replace(/^sha256=/, '');
  const expected = Buffer.from(expectedHex, 'hex');
  const received = Buffer.from(receivedHex, 'hex');
  return (
    expected.length === received.length &&
    crypto.timingSafeEqual(expected, received)
  );
}
 
app.post(
  '/webhooks/actuallycare',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.get('X-Webhook-Signature');
    if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
      return res.status(401).send('invalid signature');
    }
 
    // Acknowledge fast, process async
    res.status(200).send('ok');
 
    const payload = JSON.parse(req.body.toString('utf8'));
    // handle payload.event, payload.data ...
  }
);

Two details that bite people: verify against the raw body (a re-serialized JSON object may not match byte-for-byte), and remember to strip the sha256= prefix from the header before comparing digests. Your webhook secret is set when you create the webhook (minimum 10 characters). The API never returns it afterward — webhook responses show "has_secret": true instead — so store it when you create it. To change it, send a new secret with PUT /v1/webhooks/:id.

Delivery and retries#

  • ActuallyCare waits up to 30 seconds for your endpoint to respond. Return a 2xx quickly and do real work asynchronously.
  • Failed deliveries are retried at 1 minute, 5 minutes, and 15 minutes after the initial attempt (up to 4 attempts total), then given up. A delivery counts as failed on a network error or on a 5xx, 408, or 429 response; other 4xx responses are treated as your endpoint rejecting the event and are not retried.
  • Retries survive server restarts, and deactivating a webhook cancels its pending retries.
  • Retries currently apply to webhooks created by someone on a team. A brokerage-wide webhook (created by a broker with no team) gets each delivery once, without retries, so check its delivery logs if you rely on it.
  • Delivery is at-least-once: your endpoint can see the same event more than once, so process idempotently. The delivery logs — visible in the app, and available via GET /v1/webhooks/:id/logs — show every attempt.

Deduplicate on the signature header value — a retried delivery carries the same signature as the original, and unlike event + timestamp it can't collide when two records fire the same event in the same instant.

Managing webhooks#

A webhook belongs to the brokerage of the person who created it. If that person is on a team, it receives that team's events; if not, it receives every event in the brokerage. Webhooks are managed by broker and system-admin roles, and you see only your own brokerage's webhooks: any other webhook ID returns 404. Two ways to manage them:

  • In the app — Settings, Webhooks tab (app.actuallycare.com/settings?tab=webhooks): create endpoints, choose events, and review delivery logs.
  • Via REST — GET/POST /v1/webhooks to list and create, PUT/DELETE /v1/webhooks/:id to update and deactivate, GET /v1/webhooks/:id/logs for delivery history. A deactivated webhook stops receiving deliveries; PUT with "active": true turns it back on.

Your endpoint must be reachable on the public internet. Deliveries to private, loopback, and link-local addresses (like localhost) are blocked, so use a tunnel when testing locally.

Ready to wire one up end to end? Follow the webhook setup guide.