Webhooks

Webhooks push events to an https URL you own when a prospect changes or a property or person is added to or removed from a list. Events come from every surface, so a change in the mobile app, a list build, a drive, or another API client reaches your endpoint the same way.

Create your first webhook

POST /v1/webhooks with a URL and the event types you want. The signing secret comes back once.

How a delivery looks

Every request is a POST with a JSON body holding one or more events:

1234567891011121314151617181920212223242526{
  "events": [
    {
      "id": "evt_10442",
      "type": "prospect.added",
      "api_version": "2026-08-26",
      "occurred_at": "2026-08-26T16:20:00.000Z",
      "organization_id": 42,
      "actor": { "type": "user", "user_id": 12, "name": "Jordan Lee", "api_key_id": null, "source": "app" },
      "data": {
        "prospect": {
          "id": "prospect_8812",
          "record_type": "property",
          "record_id": "prop_12345",
          "lifecycle": "active",
          "favorite": false,
          "source": "app",
          "record": { "address": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701", "latitude": 30.2672, "longitude": -97.7431 },
          "tags": [{ "id": "tag_1", "name": "Hot", "badge_variant": "destructive", "is_system": true }],
          "created_at": "2026-08-26T16:20:00.000Z",
          "updated_at": "2026-08-26T16:20:00.000Z"
        }
      }
    }
  ]
}

Headers on every request:

Header	Meaning
`DealMachine-Signature`	`t=<unix seconds>,v1=<hmac>`; see Signatures
`DealMachine-Delivery-Id`	Unique per request; the same value is resent on a retry
`DealMachine-Event-Types`	Comma-separated types in this body
`Content-Type`	`application/json`

Answer with any 2xx status within 20 seconds. Anything else, or a timeout, is retried; see Retries.

Batches

Events for one webhook are grouped into requests of up to batch_max events (default 50, set it to 1 for one event per request). Events inside a body are in the order they happened, and a webhook never receives a later batch before an earlier one has been accepted. A large list build produces one prospect.added per record; those drain to your endpoint at a steady pace rather than all at once.

What you receive

The data.prospect object is the same shape GET /v1/prospects/{id} returns. Phone numbers and emails on person prospects are left out unless the webhook was created with include_contacts: true, since that data is credit-bearing. Files carry a download_url that works for 24 hours.

The full list of event types, each with an example body, is at Events and from GET /v1/webhooks/events.

Managing webhooks

Everything is available from the API (/v1/webhooks), the CLI (dm webhooks), and the MCP server (dealmachine_webhook_list, dealmachine_webhook_create). Each workspace can have up to 25 webhooks. The delivery log for a webhook keeps 30 days of attempts with status, response code, latency, and any error, and any delivery can be sent again.