# Webhooks & Callbacks

**GET /docs/webhooks**

Webhooks allow you to receive real-time notifications when reports are created, updated, or deleted. This is useful for tracking report status, integrating with your CRM, and automating lead management.

## How Webhooks Work
1. Include `callback_url` parameter in your API request
2. Cloud CMA creates the report
3. When the report status changes (created, updated, deleted), Cloud CMA POSTs to your callback URL
4. Your system processes the webhook and takes action (send email, log to CRM, etc.)

## Optional Parameters
- `callback_url` (optional): URL where Cloud CMA will POST webhook updates
- `job_id` (optional): Your unique tracking ID that will be included in all webhook payloads for this report

## Webhook Payload Format
Cloud CMA POSTs JSON to your callback_url:
```json
{
  "id": 12345,
  "user_id": 67890,
  "type": "Cma",
  "title": "The Robertsons",
  "notes": "",
  "mls_code": "crmls",
  "created_at": "2015-07-21T18:04:24Z",
  "updated_at": "2015-07-21T18:04:24Z",
  "deleted_at": null,
  "edit_url": "https://cloudcma.com/cmas/12345/edit",
  "pdf_url": "https://cloudcma.com/pdf/f6f280a379b61c88e9bb68c6f996d501",
  "action": "update",
  "job_id": "your-tracking-id"
}
```

## Webhook Actions
- `create`: Report was just created
- `update`: Report was updated (usually when PDF is ready)
- `delete`: Report was deleted

## Implementation Requirements
1. Your endpoint must return HTTP 200 within 30 seconds
2. Your endpoint should be publicly accessible (not localhost or private network)
3. Use HTTPS when possible
4. Cloud CMA will retry failed webhooks automatically (several attempts with backoff)
5. Store the job_id and pdf_url immediately for permanent reference

## Use Cases
### Scenario 1: Cloud CMA Handles Email
Don't provide `job_id`, provide `callback_url`. Cloud CMA creates report and:
- Sends email to consumer with report link
- POSTs webhook to your callback_url when report is ready
- You log the report in your system for tracking

### Scenario 2: Your System Handles Email
Provide both `callback_url` and `job_id`, but don't provide consumer email. Cloud CMA creates report and:
- POSTs webhook to your callback_url with pdf_url
- Your system uses job_id to look up which consumer requested it
- Your system sends custom-formatted email with your branding

### Scenario 3: Homebeat Tracking
For Homebeat automations with `callback_url`, Cloud CMA:
- POSTs on each frequency update (monthly, quarterly, etc.)
- Includes pdf_url for each update
- Allows you to track view counts and engagement
- If no consumer email provided, you handle all email delivery


## Servers
- Production API: https://cloudcma.com (Production API)


## Authentication methods
- Api key


## Parameters




## Responses
### 200
Webhooks documentation


[Powered by Bump.sh](https://bump.sh)