🔔

Webhooks API

Register webhook endpoints to receive real-time HTTP notifications when events occur in CaseHug. You can subscribe to specific event types and CaseHug will POST a JSON payload to your URL.

Looking for webhook event payloads and signature verification? See the Webhook Events reference →

POST/api/v1/webhooks

Create Webhook

Creates a new webhook endpoint. The signing_secret is returned only on creation — store it securely. It cannot be retrieved again.

Authentication

Requires webhooks:write scope.

Request Body

json

{
  "url": "https://your-app.com/webhooks/casehug",
  "events": [
    "matter.created",
    "document.uploaded",
    "document.approved",
    "intake.completed"
  ],
  "description": "Production webhook for matter updates",
  "active": true
}

Request Body Fields

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint to deliver events to
events	string[]	Yes	Event types to subscribe to. Use ["*"] for all events
description	string	No	Internal label for this webhook
active	boolean	No	Whether to deliver events (default: true)

Available Event Types

Event	Description
matter.created	A new matter was created
matter.updated	A matter was updated
matter.archived	A matter was archived
client.created	A new client was created
document.uploaded	A client uploaded a document
document.approved	A document was approved
document.rejected	A document was rejected
intake.completed	Client completed the intake form
intake.link.sent	Intake link was sent to client
*	Subscribe to all events

Response (201)

json

{
  "data": {
    "id": "wh_01HXYZ",
    "url": "https://your-app.com/webhooks/casehug",
    "events": [
      "matter.created",
      "document.uploaded",
      "document.approved",
      "intake.completed"
    ],
    "description": "Production webhook for matter updates",
    "active": true,
    "signing_secret": "whsec_a8b3c2d1e4f5...",
    "created_at": "2024-03-07T14:00:00Z",
    "updated_at": "2024-03-07T14:00:00Z"
  }
}

⚠️

The signing_secret is only returned once. Store it immediately in your environment secrets — you cannot retrieve it later.

Code Examples

curl -X POST https://api.calmintake.com/api/v1/webhooks \
  -H "X-Api-Key: ch_live_sk_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/casehug",
    "events": ["matter.created", "document.uploaded"],
    "active": true
  }'

GET/api/v1/webhooks

List Webhooks

Returns all registered webhook endpoints for your firm. Signing secrets are not included in list responses.

Authentication

Requires webhooks:read scope.

Response (200)

json

{
  "data": [
    {
      "id": "wh_01HXYZ",
      "url": "https://your-app.com/webhooks/casehug",
      "events": ["matter.created", "document.uploaded"],
      "description": "Production webhook",
      "active": true,
      "last_triggered_at": "2024-03-07T15:30:00Z",
      "created_at": "2024-03-07T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 2,
    "has_more": false
  }
}

PATCH/api/v1/webhooks/:id

Update Webhook

Update webhook settings. Use this to change subscribed events, toggle active status, or update the description.

Authentication

Requires webhooks:write scope.

Request Body

json

{
  "events": [
    "matter.created",
    "document.uploaded",
    "document.approved",
    "document.rejected",
    "intake.completed",
    "matter.archived"
  ],
  "active": true,
  "description": "All events — production"
}

Returns updated webhook object with status 200.

DELETE/api/v1/webhooks/:id

Delete Webhook

Permanently deletes a webhook endpoint. No more events will be delivered to this URL. This action cannot be undone. No request body required.

Authentication

Requires webhooks:write scope.

Response (200)

json

{
  "data": {
    "id": "wh_01HXYZ",
    "deleted": true
  }
}

POST/api/v1/webhooks/:id/test

Test Webhook

Sends a test event to the webhook URL to verify your endpoint is receiving events correctly. The test event has type webhook.test. No request body required.

Authentication

Requires webhooks:write scope.

Response (200)

json

{
  "data": {
    "webhook_id": "wh_01HXYZ",
    "event": "webhook.test",
    "delivered": true,
    "response_status": 200,
    "response_time_ms": 143,
    "sent_at": "2024-03-07T14:10:00Z"
  }
}

Error Responses

Status	Code	Description
404	webhook_not_found	Webhook with that ID does not exist
422	webhook_inactive	Webhook is disabled — enable it first
502	delivery_failed	Endpoint did not return 2xx within 5 seconds