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

# Webhook event types

> Every webhook event Scribe can send: conversions, visitors, signatures, teammates, campaigns and integrations — with payload examples.

Every event payload carries a `type` field naming the event and an `occurred_at` ISO 8601 timestamp. All resource references are the same uuids the [REST API](/api-reference/introduction) serves, so you can always fetch the full resource after receiving an event.

Subscribe to specific event types per endpoint in the webhook portal, or subscribe to all of them — see the [overview](/api-reference/webhooks/overview) for setup and signature verification.

## Conversions & visitors

### `conversion.recorded`

An attributed conversion event was accepted for your workspace. Only click-attributed, deduplicated conversions are delivered — the same gating as [conversion tracking](/api-reference/use-cases) itself.

```json theme={null}
{
  "type": "conversion.recorded",
  "event_id": "order-1042",
  "name": "purchase",
  "value": 99.0,
  "currency": "USD",
  "source": "api",
  "occurred_at": "2026-08-11T09:30:00Z",
  "visitor": {
    "anonymous_id": "5f2c...",
    "user_id": "user-42"
  },
  "attribution": {
    "teammate_uuid": "7d3f0e58-...",
    "signature_template_uuid": "a1b2c3d4-...",
    "anchor_uuid": "e5f6a7b8-...",
    "email_uuid": "c9d0e1f2-...",
    "marketing_campaign_uuid": ""
  },
  "properties": { "plan": "pro" }
}
```

`event_id` is the idempotency key you supplied when tracking the event (may be null). Attribution uuids are empty strings when unresolved.

### `visitor.identified`

A signature-attributed visitor was identified for the first time — a `user_id` your workspace had never seen before. Re-identifies of a known visitor (for example on every page load) do not fire. Fetch the full profile at `GET /v1/analytics/visitors/{visitor.id}`.

```json theme={null}
{
  "type": "visitor.identified",
  "visitor": {
    "id": "b4c5d6e7-...",
    "user_id": "user-42",
    "anonymous_id": "5f2c...",
    "identified_via": "browser",
    "first_seen_at": "2026-08-11T09:28:12Z",
    "traits": { "email": "ada@example.com" }
  },
  "attribution": {
    "click_id": "f1e2d3c4-...",
    "teammate_uuid": "7d3f0e58-...",
    "signature_template_uuid": "a1b2c3d4-...",
    "email_uuid": "c9d0e1f2-..."
  },
  "occurred_at": "2026-08-11T09:28:12Z"
}
```

## Signatures

### `signature.published`

A signature's draft was published (made live). Covers primary signatures and reply/internal variants — `signature.kind` discriminates.

```json theme={null}
{
  "type": "signature.published",
  "signature": {
    "uuid": "a1b2c3d4-...",
    "name": "Sales team",
    "kind": "primary",
    "folder_uuid": "d4e5f6a7-..."
  },
  "occurred_at": "2026-08-11T10:00:00Z"
}
```

`name` and `folder_uuid` are null for variants. `kind` is one of `primary`, `reply_variant`, `internal_variant`.

### `signature.installation.failed`

Installing a signature into a specific mailbox failed. Fired once per failure transition — a mailbox that stays broken does not re-fire daily; after a successful reinstall, a new failure fires again.

```json theme={null}
{
  "type": "signature.installation.failed",
  "error_code": "user_not_found",
  "email": {
    "uuid": "c9d0e1f2-...",
    "address": "ada@acme.com"
  },
  "teammate_uuid": "7d3f0e58-...",
  "signature": {
    "uuid": "a1b2c3d4-...",
    "name": "Sales team",
    "kind": "primary"
  },
  "integration": {
    "uuid": "9a8b7c6d-...",
    "kind": "google_workspace_gmail"
  },
  "occurred_at": "2026-08-11T04:00:00Z"
}
```

Known `error_code` values: `user_not_found`, `forbidden`, `unauthorized_client`, `channel_not_found`, `signature_too_long`, `multi_signatures_not_supported`. New codes may be added over time.

## Teammates

### `teammate.created`

A teammate was added to your workspace — by a user in the dashboard, through the API, or by a directory sync importing a new person.

```json theme={null}
{
  "type": "teammate.created",
  "teammate": {
    "uuid": "7d3f0e58-...",
    "display_name": "Ada Lovelace"
  },
  "emails": [
    { "uuid": "c9d0e1f2-...", "address": "ada@acme.com", "primary": true }
  ],
  "occurred_at": "2026-08-11T11:00:00Z"
}
```

### `teammate.deleted`

A teammate was removed — by a user or by a directory sync removing a departed person. Fired at removal time; the payload is your last chance to read the teammate's identifiers.

```json theme={null}
{
  "type": "teammate.deleted",
  "teammate": {
    "uuid": "7d3f0e58-...",
    "display_name": "Ada Lovelace"
  },
  "emails": [
    { "uuid": "c9d0e1f2-...", "address": "ada@acme.com", "primary": true }
  ],
  "occurred_at": "2026-08-11T11:30:00Z"
}
```

## Campaigns

All five campaign events share the same payload shape:

```json theme={null}
{
  "type": "campaign.started",
  "campaign": {
    "uuid": "3c4d5e6f-...",
    "name": "Summer promo",
    "status": "active",
    "start_time": "2026-08-12T07:00:00Z",
    "end_time": "2026-08-20T16:00:00Z",
    "time_zone": "Europe/Brussels",
    "signature_template_uuids": ["a1b2c3d4-..."]
  },
  "occurred_at": "2026-08-12T07:12:00Z"
}
```

| Event                | Fired when                                                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `campaign.scheduled` | A user scheduled a campaign for a future start                                                                                                   |
| `campaign.started`   | The campaign went live — immediately at schedule time if the start was already due, or when its start time is reached (checked every 30 minutes) |
| `campaign.paused`    | A user paused a live campaign                                                                                                                    |
| `campaign.resumed`   | A user resumed a paused campaign                                                                                                                 |
| `campaign.ended`     | The campaign reached its end time and was archived (checked every 30 minutes)                                                                    |

`status` reflects the post-transition state: `draft`, `scheduled`, `active`, `paused` or `archived`.

## Integrations

### `integration.connected`

An integration was connected and became active for the first time. Re-authentications of an already-connected integration do not fire.

```json theme={null}
{
  "type": "integration.connected",
  "integration": {
    "uuid": "9a8b7c6d-...",
    "kind": "google_workspace_gmail",
    "category": "signatures",
    "name": "Gmail"
  },
  "occurred_at": "2026-08-11T14:00:00Z"
}
```

`category` is one of `teammates`, `signatures`, `smart_fields`, `assets`.

### `integration.access_lost`

Scribe lost access to a connected integration (revoked or expired credentials). Signature installs and teammate syncs through this integration are paused until an admin reconnects it — `reconnect_url` deep-links straight to the fix. Fired once per loss; a reconnect re-arms it.

```json theme={null}
{
  "type": "integration.access_lost",
  "integration": {
    "uuid": "9a8b7c6d-...",
    "kind": "google_workspace_gmail",
    "category": "signatures",
    "name": "Gmail"
  },
  "error_message": "invalid_grant",
  "reconnect_url": "https://app.scribe-mail.com/integrations?integrationId=12",
  "occurred_at": "2026-08-11T15:00:00Z"
}
```

### `integration.disconnected`

An integration was disconnected (removed) by a user.

```json theme={null}
{
  "type": "integration.disconnected",
  "integration": {
    "uuid": "9a8b7c6d-...",
    "kind": "google_workspace_gmail",
    "category": "signatures",
    "name": "Gmail"
  },
  "occurred_at": "2026-08-11T16:00:00Z"
}
```