Skip to content
For developers

Webhooks API

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

Last updated

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 in your brokerage. Requires the broker or system admin role. Secrets are never returned.

Parameters#

ParameterInTypeRequiredDescription
pagequeryintegerNoPage number for pagination · Default: 1 · Min: 1
limitqueryintegerNoNumber of items per page (default 25, max 100) · Default: 25 · Max: 100 · Min: 1

Responses#

StatusMeaningWhat to do
200Webhook subscriptions
401Authentication requiredSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
403Requires broker or system admin roleCheck the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

This endpoint takes a JWT, not an API key. How to get one.
GET /v1/webhooks

Enter a token to send.

Example response (200)#

{
  "success": true,
  "data": [
    {
      "id": "wh_abc123def456",
      "url": "example url",
      "events": [
        "escrow.created"
      ],
      "has_secret": true,
      "active": true,
      "brokerage_id": "550e8400-e29b-41d4-a716-446655440000",
      "team_id": "550e8400-e29b-41d4-a716-446655440000",
      "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#

FieldTypeRequiredDescription
urlstringYesEndpoint to deliver events to · Format: uri
eventsarray of stringsYesEvent names to subscribe to (see GET /webhooks/events for the catalog)
secretstringYesShared secret used to sign every delivery

Responses#

StatusMeaningWhat to do
201Webhook created
400Invalid request dataFix the request; error.message and error.details name the problem. Don't retry unchanged
401Authentication requiredSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
403Requires broker or system admin roleCheck the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

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"
  }'

Example response (201)#

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "url": "example url",
    "events": [
      "escrow.created"
    ],
    "has_secret": true,
    "active": true,
    "brokerage_id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "550e8400-e29b-41d4-a716-446655440000",
    "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#

ParameterInTypeRequiredDescription
categoryquerystringNoFilter to a single category (e.g. escrow, lead, email)

Responses#

StatusMeaningWhat to do
200Event catalog
401Authentication requiredSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
403Requires broker or system admin roleCheck the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

This endpoint takes a JWT, not an API key. How to get one.
GET /v1/webhooks/events

Enter a token to send.

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#

StatusMeaningWhat to do
200Categories with event counts
401Authentication requiredSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
403Requires broker or system admin roleCheck the ID first: an ID that doesn't exist or isn't yours also returns 403. Otherwise a role or key-scope problem; retrying won't help. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

This endpoint takes a JWT, not an API key. How to get one.
GET /v1/webhooks/events/categories

Enter a token to send.

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#

ParameterInTypeRequiredDescription
idpathstringYesWebhook ID

Request body#

FieldTypeRequiredDescription
urlstringNoEndpoint that receives event deliveries · Format: uri
eventsarray of stringsNoSubscribed event names (entity.action format)
activebooleanNoWhether the subscription is enabled to receive deliveries
secretstringNoShared secret used to sign deliveries (minimum 10 characters)

Responses#

StatusMeaningWhat to do
200Webhook updated
400Invalid request dataFix the request; error.message and error.details name the problem. Don't retry unchanged
401Authentication requiredSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

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"
  }'

Example response (200)#

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "url": "example url",
    "events": [
      "escrow.created"
    ],
    "has_secret": true,
    "active": true,
    "brokerage_id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "550e8400-e29b-41d4-a716-446655440000",
    "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#

ParameterInTypeRequiredDescription
idpathstringYesWebhook ID

Responses#

StatusMeaningWhat to do
200Webhook deactivated (response is the updated subscription with active=false)
401Authentication requiredSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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

Example response (200)#

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "url": "example url",
    "events": [
      "escrow.created"
    ],
    "has_secret": true,
    "active": true,
    "brokerage_id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "550e8400-e29b-41d4-a716-446655440000",
    "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#

ParameterInTypeRequiredDescription
idpathstringYesWebhook ID
pagequeryintegerNoPage number for pagination · Default: 1 · Min: 1
limitqueryintegerNoNumber of items per page (default 25, max 100) · Default: 25 · Max: 100 · Min: 1

Responses#

StatusMeaningWhat to do
200Delivery log entries, most recent first
401Authentication requiredSend a JWT as Authorization: Bearer … — this endpoint rejects API keys. See Authentication
404Resource not foundCheck the ID. Most record lookups (all but contacts) answer an unknown ID with 403, not 404. See Errors
429Rate limit exceeded — too many requests in the current window. Wait for the window to reset (see Retry-After) before retrying.Back off and retry after Retry-After. See Rate limits
500Internal server errorRetry with exponential backoff. See Errors

Example request#

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

Try it

Sends a real request from your browser to the API, as you. GET requests only read data.

This endpoint takes a JWT, not an API key. How to get one.
GET /v1/webhooks//logs

Enter a token to send.

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"
    }
  ]
}