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

# Outreach Webhooks

> Manage outreach webhook subscriptions via the REST API (OAuth-driven app integrations).

## Create a webhook subscription

`POST /api/v1/sites/{siteId}/outreach/webhooks`

Create a webhook subscription so Sight AI POSTs outreach events to your endpoint. Used by app integrations after the OAuth flow completes — your app gets an access token, then calls this endpoint to register its webhook URL and choose which events to receive.

### Required headers

| Header          | Required | Description                                                                                                                    |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `Authorization` | Yes      | `Bearer sai_<64hex>` (API key) OR `Bearer sai_oauth_*` (OAuth access token). See [Authentication](/developers/authentication). |
| `Content-Type`  | Yes      | `application/json`.                                                                                                            |

### Request body

| Field        | Type      | Required | Description                                                                                                                             |
| ------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `label`      | string    | Yes      | A name for your reference (max 120 chars).                                                                                              |
| `url`        | string    | Yes      | The HTTPS URL Sight AI POSTs events to (max 2000 chars).                                                                                |
| `eventTypes` | string\[] | Yes      | The subset of events to receive. Must be non-empty; each value must be in the [event catalog](/developers/webhooks#when-webhooks-fire). |

### Response

#### 201 Created

```json theme={null}
{
  "subscription": {
    "id": "sub_abc123",
    "team_id": "team_xyz",
    "site_id": "site_abc123",
    "label": "CRM — inbound handler",
    "url": "https://your-app.com/webhooks/sightai",
    "secret_prefix": "sightai_wh_abc…",
    "event_types": ["outreach.reply_sent", "outreach.conversation_status_changed"],
    "is_active": true,
    "consecutive_failures": 0,
    "created_by_oauth_client_id": "sightai_client123",
    "created_at": "2026-06-29T12:00:00Z",
    "updated_at": "2026-06-29T12:00:00Z",
    "last_delivery_at": null,
    "last_delivery_status": null
  },
  "secret": "sightai_wh_<full-secret-shown-once>"
}
```

The `secret` is the HMAC signing secret. **Copy it now — it's never shown again.** You'll use it to verify the `SightAI-Signature` header on incoming webhooks. The `subscription` object returned (and all subsequent reads) only includes `secret_prefix`, never the full secret.

When the caller is an OAuth token, `created_by_oauth_client_id` is stamped with the owning client so revoking that client cascades to delete this subscription. For API-key callers, it's `null`.

#### Error responses

| Status | Code                 | Meaning                                                      |
| ------ | -------------------- | ------------------------------------------------------------ |
| 400    | `VALIDATION_ERROR`   | Invalid body (bad URL, empty eventTypes, unknown event type) |
| 401    | `UNAUTHORIZED`       | Missing or invalid credentials                               |
| 403    | `INSUFFICIENT_SCOPE` | Credentials lack `webhooks:write`                            |
| 403    | `SITE_NOT_LICENSED`  | Site does not have an active license                         |
| 404    | `SITE_NOT_FOUND`     | Site doesn't exist or isn't owned by the credential's team   |

### Example

```bash theme={null}
curl -X POST https://app.trysight.ai/api/v1/sites/site_abc123/outreach/webhooks \
  -H "Authorization: Bearer sai_oauth_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "CRM — inbound handler",
    "url": "https://your-app.com/webhooks/sightai",
    "eventTypes": ["outreach.reply_sent", "outreach.conversation_status_changed", "outreach.contact_suppressed"]
  }'
```

## List webhook subscriptions

`GET /api/v1/sites/{siteId}/outreach/webhooks`

List all webhook subscriptions for a site. Returns the safe shape (no plaintext secrets).

### Response

```json theme={null}
{
  "subscriptions": [
    {
      "id": "sub_abc123",
      "label": "CRM — inbound handler",
      "url": "https://your-app.com/webhooks/sightai",
      "secret_prefix": "sightai_wh_abc…",
      "event_types": ["outreach.reply_sent"],
      "is_active": true,
      "consecutive_failures": 0,
      "created_by_oauth_client_id": "sightai_client123",
      "created_at": "2026-06-29T12:00:00Z",
      "last_delivery_at": "2026-06-29T12:05:00Z",
      "last_delivery_status": "ok"
    }
  ]
}
```

Requires the `webhooks:read` scope.

## Delete a webhook subscription

`DELETE /api/v1/sites/{siteId}/outreach/webhooks/{id}`

Delete a webhook subscription. The subscription's delivery history is cascaded (deleted automatically). Requires the `webhooks:write` scope.

### Response

```json theme={null}
{ "success": true }
```

Returns `404 NOT_FOUND` if the subscription doesn't exist or doesn't belong to the site.

## Revoking an app's access

To revoke an app integration's access entirely (all its subscriptions + tokens), delete its OAuth client in **Integrations → Sight AI API → OAuth apps**. This cascades to delete every webhook subscription that client created and revokes its outstanding access/refresh tokens. See [Webhooks](/developers/webhooks#the-oauth-flow) for the full OAuth flow.

<Note>
  Subscription management is API-only — there is no dashboard form. The only dashboard surface for revoking a platform's webhooks is deleting its OAuth client.
</Note>