Webhooks API

REST endpoints for webhooks — request and response reference with examples.

Manage webhook subscriptions and browse the self-documenting event catalog. Concepts and signature verification live in Webhooks; the hands-on walkthrough is Set up webhooks.

Base URL: https://api.actuallycare.com/v1 · Errors use the standard envelope — see Errors.

List webhook subscriptions#

GET/v1/webhooks

Returns the webhook subscriptions registered for your account. Requires the broker or system admin role.

Parameters#

Parameter	In	Type	Required	Description
`page`	query	integer	No	Page number for pagination · Default: `1` · Min: 1
`limit`	query	integer	No	Number of items per page (default 25; GET /escrows overrides this to 20 at the controller level) · Default: `25` · Max: 100 · Min: 1

Responses#

Status	Meaning
`200`	Webhook subscriptions
`401`	Authentication required
`403`	Requires broker or system admin role
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/webhooks", {
  headers: {
    "Authorization": "Bearer YOUR_JWT",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.get(
    "https://api.actuallycare.com/v1/webhooks",
    headers={"Authorization": "Bearer YOUR_JWT"},
)
data = resp.json()

Example response (200)#

{
  "success": true,
  "data": [
    {
      "id": "wh_abc123def456",
      "url": "example url",
      "events": [
        "escrow.created"
      ],
      "secret": "example secret",
      "active": true,
      "last_triggered": "2026-07-15T14:32:10.000Z",
      "created_at": "2026-07-15T14:32:10.000Z"
    }
  ]
}

Create a webhook subscription#

POST/v1/webhooks

Registers an endpoint to receive event notifications. Each delivery is an HTTPS POST with the JSON payload, an X-Webhook-Event header naming the event, an X-Webhook-Timestamp header, and an X-Webhook-Signature header containing sha256= followed by the hex-encoded HMAC-SHA256 of the payload computed with your secret. Each event gets 4 delivery attempts total: the initial delivery plus retries after 1, 5, and 15 minutes. Only HTTP 5xx, 408, and 429 responses (and network failures) are retried — any other 4xx response is logged and NOT retried.

Request body#

Field	Type	Required	Description
`url`	string	Yes	Endpoint to deliver events to · Format: uri
`events`	array of strings	Yes	Event names to subscribe to (see GET /webhooks/events for the catalog)
`secret`	string	Yes	Shared secret used to sign every delivery

Responses#

Status	Meaning
`201`	Webhook created
`400`	Invalid request data
`401`	Authentication required
`403`	Requires broker or system admin role
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

curl -X POST "https://api.actuallycare.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "your-url",
    "events": [
      "escrow.created"
    ],
    "secret": "your-secret"
  }'

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_JWT",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "your-url",
    "events": [
      "escrow.created"
    ],
    "secret": "your-secret"
  }),
});
const data = await res.json();

Python

import requests
 
resp = requests.post(
    "https://api.actuallycare.com/v1/webhooks",
    headers={"Authorization": "Bearer YOUR_JWT"},
    json={
        "url": "your-url",
        "events": [
            "escrow.created"
        ],
        "secret": "your-secret"
    },
)
data = resp.json()

Example response (201)#

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "url": "example url",
    "events": [
      "escrow.created"
    ],
    "secret": "example secret",
    "active": true,
    "last_triggered": "2026-07-15T14:32:10.000Z",
    "created_at": "2026-07-15T14:32:10.000Z"
  }
}

List available webhook events#

GET/v1/webhooks/events

Returns the catalog of events you can subscribe to, including each event's category, description, and the field names included in its payload.

Parameters#

Parameter	In	Type	Required	Description
`category`	query	string	No	Filter to a single category (e.g. escrow, lead, email)

Responses#

Status	Meaning
`200`	Event catalog
`401`	Authentication required
`403`	Requires broker or system admin role
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/webhooks/events", {
  headers: {
    "Authorization": "Bearer YOUR_JWT",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.get(
    "https://api.actuallycare.com/v1/webhooks/events",
    headers={"Authorization": "Bearer YOUR_JWT"},
)
data = resp.json()

Example response (200)#

{
  "success": true,
  "data": [
    {
      "event": "escrow.created",
      "category": "escrow",
      "description": "example description",
      "payload": [
        "example payload"
      ]
    }
  ],
  "meta": {
    "total": 150,
    "categories": [
      "escrow"
    ]
  }
}

List webhook event categories#

GET/v1/webhooks/events/categories

Returns every event category with the number of events it contains.

Responses#

Status	Meaning
`200`	Categories with event counts
`401`	Authentication required
`403`	Requires broker or system admin role
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/webhooks/events/categories", {
  headers: {
    "Authorization": "Bearer YOUR_JWT",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.get(
    "https://api.actuallycare.com/v1/webhooks/events/categories",
    headers={"Authorization": "Bearer YOUR_JWT"},
)
data = resp.json()

Example response (200)#

{
  "success": true,
  "data": [
    {
      "category": "escrow",
      "event_count": 3
    }
  ]
}

Update a webhook subscription#

PUT/v1/webhooks/{id}

Updates a subscription's URL, events, secret, or active flag. Only the fields you send are changed.

Parameters#

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Webhook ID

Request body#

Field	Type	Required	Description
`url`	string	No	Endpoint that receives event deliveries · Format: uri
`events`	array of strings	No	Subscribed event names (entity.action format)
`active`	boolean	No	Whether the subscription is enabled to receive deliveries
`secret`	string	No	Shared secret used to sign deliveries (minimum 10 characters)

Responses#

Status	Meaning
`200`	Webhook updated
`400`	Invalid request data
`401`	Authentication required
`404`	Resource not found
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

curl -X PUT "https://api.actuallycare.com/v1/webhooks/:id" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "your-url",
    "events": [
      "your-events"
    ],
    "active": true,
    "secret": "your-secret"
  }'

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/webhooks/:id", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_JWT",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "your-url",
    "events": [
      "your-events"
    ],
    "active": true,
    "secret": "your-secret"
  }),
});
const data = await res.json();

Python

import requests
 
resp = requests.put(
    "https://api.actuallycare.com/v1/webhooks/:id",
    headers={"Authorization": "Bearer YOUR_JWT"},
    json={
        "url": "your-url",
        "events": [
            "your-events"
        ],
        "active": true,
        "secret": "your-secret"
    },
)
data = resp.json()

Example response (200)#

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "url": "example url",
    "events": [
      "escrow.created"
    ],
    "secret": "example secret",
    "active": true,
    "last_triggered": "2026-07-15T14:32:10.000Z",
    "created_at": "2026-07-15T14:32:10.000Z"
  }
}

Deactivate a webhook subscription#

DELETE/v1/webhooks/{id}

Deactivates a subscription so it stops receiving deliveries. The subscription record is kept and can be re-enabled by setting active back to true.

Parameters#

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Webhook ID

Responses#

Status	Meaning
`200`	Webhook deactivated (response is the updated subscription with active=false)
`401`	Authentication required
`404`	Resource not found
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/webhooks/:id", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer YOUR_JWT",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.delete(
    "https://api.actuallycare.com/v1/webhooks/:id",
    headers={"Authorization": "Bearer YOUR_JWT"},
)
data = resp.json()

Example response (200)#

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "url": "example url",
    "events": [
      "escrow.created"
    ],
    "secret": "example secret",
    "active": true,
    "last_triggered": "2026-07-15T14:32:10.000Z",
    "created_at": "2026-07-15T14:32:10.000Z"
  },
  "timestamp": "2026-07-01T22:51:14.902Z"
}

Get webhook delivery logs#

GET/v1/webhooks/{id}/logs

Returns recent delivery attempts for a subscription, including the payload sent, the HTTP status your endpoint returned, and whether delivery succeeded.

Parameters#

Parameter	In	Type	Required	Description
`id`	path	string	Yes	Webhook ID
`page`	query	integer	No	Page number for pagination · Default: `1` · Min: 1
`limit`	query	integer	No	Number of items per page (default 25; GET /escrows overrides this to 20 at the controller level) · Default: `25` · Max: 100 · Min: 1

Responses#

Status	Meaning
`200`	Delivery log entries, most recent first
`401`	Authentication required
`404`	Resource not found
`429`	Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.
`500`	Internal server error

Example request#

cURL

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

JavaScript

const res = await fetch("https://api.actuallycare.com/v1/webhooks/:id/logs", {
  headers: {
    "Authorization": "Bearer YOUR_JWT",
  },
});
const data = await res.json();

Python

import requests
 
resp = requests.get(
    "https://api.actuallycare.com/v1/webhooks/:id/logs",
    headers={"Authorization": "Bearer YOUR_JWT"},
)
data = resp.json()

Example response (200)#

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
      "event": "escrow.created",
      "payload": {},
      "response_status": 200,
      "delivered_at": "2026-07-15T14:32:10.000Z",
      "created_at": "2026-07-15T14:32:10.000Z"
    }
  ]
}