> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breakcold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Understand outbound Breakcold webhooks, delivery headers, signatures, and event payloads.

Breakcold outbound webhooks send events from your workspace to an HTTPS endpoint you control. Use them when another system needs to react to CRM changes such as records, notes, tasks, relations, calls, or files.

## Event categories

* [Record Webhooks](/api/webhooks/records): Payloads for record created, updated, and deleted events.
* [Note Webhooks](/api/webhooks/notes): Payloads for note created, updated, and deleted events.
* [Task Webhooks](/api/webhooks/tasks): Payloads for task created and completed events.
* [Relation Webhooks](/api/webhooks/relations): Payloads for relation added and removed events.
* [Call Webhooks](/api/webhooks/calls): Payloads for call linked and unlinked events.
* [File Webhooks](/api/webhooks/files): Payloads for file uploaded and deleted events.

## Create an endpoint

1. Open Breakcold.
2. Go to **Settings**.
3. Open **Webhook**.
4. Open **Send**.
5. Click **New outbound webhook**.
6. Enter your HTTPS endpoint URL.
7. Select the events you want to receive.
8. Optionally filter deliveries to specific object types.
9. Copy the signing secret.

Breakcold only delivers to active endpoints that subscribe to the event. If you add an object type filter, record-based events are only sent when the record belongs to one of those object types.

## Delivery

Breakcold sends each webhook as an HTTP `POST` request with a JSON body. Your endpoint should return any `2xx` status when it accepts the delivery.

If delivery fails, Breakcold retries up to 3 attempts total. Retries currently run after about 5 seconds and then 30 seconds. Requests time out after 10 seconds. Endpoints are disabled after 50 consecutive delivery failures.

Delivery logs are kept for 30 days.

## Headers

Each delivery includes these headers.

| Header                  | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `Content-Type`          | Always `application/json`.                               |
| `X-Webhook-Signature`   | HMAC-SHA256 signature in the format `sha256=HEX_DIGEST`. |
| `X-Webhook-Event`       | The event name, such as `record.created`.                |
| `X-Webhook-Delivery-Id` | The delivery event id. Use it for idempotency.           |
| `X-Webhook-Timestamp`   | Unix timestamp in seconds used for signing.              |
| `User-Agent`            | `Breakcold-Webhooks/1.0`.                                |

## Verify signatures

Use the endpoint signing secret to verify that a request came from Breakcold. The signed string is `${timestamp}.${rawBody}`, where `timestamp` is the `X-Webhook-Timestamp` header and `rawBody` is the exact request body string.

```js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyBreakcoldWebhook({
  rawBody,
  timestamp,
  signatureHeader,
  signingSecret,
}) {
  const expected =
    "sha256=" +
    createHmac("sha256", signingSecret)
      .update(timestamp + "." + rawBody)
      .digest("hex");

  return timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}
```

## Payload envelope

Every event uses the same envelope.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "record.created",
  "data": {
    "id": "record_id",
    "objectType": "person",
    "objectTypeName": "Person",
    "name": "Ada Lovelace",
    "fields": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Analytical Engines Ltd"
    },
    "createdAt": "2026-03-19T12:00:00.000Z",
    "updatedAt": "2026-03-19T12:00:00.000Z"
  }
}
```

| Field         | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `event`       | Event type.                                                         |
| `eventId`     | Unique delivery event id.                                           |
| `timestamp`   | ISO timestamp generated when Breakcold builds the delivery payload. |
| `workspaceId` | Workspace where the event happened.                                 |
| `data`        | Event-specific payload.                                             |

## Test event

The endpoint test button sends a `webhook.test` event with a valid signature. Use it to confirm that your endpoint is reachable and that signature verification works.

```json theme={null}
{
  "event": "webhook.test",
  "eventId": "evt_test_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "data": {
    "message": "This is a test webhook delivery from Breakcold."
  }
}
```

## Events

| Event              | Category      | When it fires                                          |
| ------------------ | ------------- | ------------------------------------------------------ |
| `record.created`   | CRM           | Fired when a new record is created.                    |
| `record.updated`   | CRM           | Fired when a record field is updated.                  |
| `record.deleted`   | CRM           | Fired when a record is deleted.                        |
| `note.created`     | Notes         | Fired when a note is added to a record.                |
| `note.updated`     | Notes         | Fired when a note is edited.                           |
| `note.deleted`     | Notes         | Fired when a note is deleted.                          |
| `task.created`     | Tasks         | Fired when a task is linked to a record.               |
| `task.completed`   | Tasks         | Fired when a task is marked as completed.              |
| `relation.added`   | CRM           | Fired when a relation is added between records.        |
| `relation.removed` | CRM           | Fired when a relation is removed between records.      |
| `call.linked`      | Communication | Fired when a call recording is linked to a record.     |
| `call.unlinked`    | Communication | Fired when a call recording is unlinked from a record. |
| `file.uploaded`    | Files         | Fired when a file is uploaded to a record.             |
| `file.deleted`     | Files         | Fired when a file is deleted from a record.            |

## Payload examples

### `record.created`

Fired when a new record is created.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "record.created",
  "data": {
    "id": "record_id",
    "objectType": "person",
    "objectTypeName": "Person",
    "name": "Ada Lovelace",
    "fields": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Analytical Engines Ltd"
    },
    "createdAt": "2026-03-19T12:00:00.000Z",
    "updatedAt": "2026-03-19T12:00:00.000Z"
  }
}
```

### `record.updated`

Fired when a record field is updated.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "record.updated",
  "data": {
    "id": "record_id",
    "objectType": "person",
    "objectTypeName": "Person",
    "name": "Ada Lovelace",
    "fields": {
      "name": "Ada Lovelace",
      "email": "ada@newdomain.example"
    },
    "createdAt": "2026-03-19T12:00:00.000Z",
    "updatedAt": "2026-03-19T12:10:00.000Z"
  }
}
```

### `record.deleted`

Fired when a record is deleted.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "record.deleted",
  "data": {
    "id": "record_id",
    "deleted": true
  }
}
```

### `note.created`

Fired when a note is added to a record.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "note.created",
  "data": {
    "recordId": "record_id",
    "noteId": "note_id",
    "title": "Follow up",
    "contentPlain": "Discussed pricing and next steps.",
    "author": "Jane Smith",
    "createdAt": "2026-03-19T12:00:00.000Z",
    "updatedAt": "2026-03-19T12:00:00.000Z"
  }
}
```

### `note.updated`

Fired when a note is edited.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "note.updated",
  "data": {
    "recordId": "record_id",
    "noteId": "note_id",
    "title": "Follow up",
    "contentPlain": "Send the pricing deck before Friday.",
    "author": "Jane Smith",
    "createdAt": "2026-03-19T12:00:00.000Z",
    "updatedAt": "2026-03-19T12:15:00.000Z"
  }
}
```

### `note.deleted`

Fired when a note is deleted.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "note.deleted",
  "data": {
    "recordId": "record_id",
    "noteId": "note_id",
    "title": "Follow up"
  }
}
```

### `task.created`

Fired when a task is linked to a record.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "task.created",
  "data": {
    "recordId": "record_id",
    "taskId": "task_id",
    "title": "Send proposal",
    "status": "todo",
    "dueAt": "2026-03-20T09:00:00.000Z"
  }
}
```

### `task.completed`

Fired when a task is marked as completed.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "task.completed",
  "data": {
    "recordId": "record_id",
    "taskId": "task_id",
    "title": "Send proposal",
    "status": "done",
    "dueAt": "2026-03-20T09:00:00.000Z"
  }
}
```

### `relation.added`

Fired when a relation is added between records.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "relation.added",
  "data": {
    "sourceRecordId": "record_id",
    "targetRecordId": "related_record_id",
    "fieldDefinitionId": "field_definition_id",
    "fieldSlug": "company"
  }
}
```

### `relation.removed`

Fired when a relation is removed between records.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "relation.removed",
  "data": {
    "sourceRecordId": "record_id",
    "targetRecordId": "related_record_id",
    "fieldDefinitionId": "field_definition_id",
    "fieldSlug": "company"
  }
}
```

### `call.linked`

Fired when a call recording is linked to a record.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "call.linked",
  "data": {
    "recordId": "record_id",
    "callId": "call_recording_id",
    "recordName": "Ada Lovelace",
    "meetingTitle": "Discovery call"
  }
}
```

### `call.unlinked`

Fired when a call recording is unlinked from a record.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "call.unlinked",
  "data": {
    "recordId": "record_id",
    "callId": "call_recording_id",
    "recordName": "Ada Lovelace",
    "meetingTitle": "Discovery call"
  }
}
```

### `file.uploaded`

Fired when a file is uploaded to a record.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "file.uploaded",
  "data": {
    "recordId": "record_id",
    "fileName": "contract.pdf"
  }
}
```

### `file.deleted`

Fired when a file is deleted from a record.

```json theme={null}
{
  "eventId": "evt_abc123",
  "timestamp": "2026-03-19T12:00:00.000Z",
  "workspaceId": "workspace_id",
  "event": "file.deleted",
  "data": {
    "recordId": "record_id",
    "fileName": "contract.pdf"
  }
}
```