# Incoming Webhooks

An **Incoming Webhook** is an HTTPS endpoint that external systems can POST events to. Each webhook generates a unique URL and, optionally, an access token used to authenticate the caller. Workflows can subscribe to that URL via `WEBHOOK` trigger nodes and react to the events.

These are **inbound only** — they don't push notifications out to your systems. (Outbound event delivery, if and when added, will be a separate concept.)

## Identity

| Field | Type | Notes |
|  --- | --- | --- |
| `id` | string | Custom prefixed ID (e.g. `clx123incomingwebhook`). |
| `name` | string | Required, min 1 character. |
| `description` | string? |  |
| `url` | string | The HTTPS endpoint to POST to. Generated by Frontline. |
| `isActive` | boolean | Default `true`. When `false`, the webhook drops incoming requests with `404`. |
| `useAuthentication` | boolean | Default `true`. Controls whether the webhook requires a Bearer token. |
| `accessToken` | string? | 64-character token. **Returned only on create** when `useAuthentication=true`. |
| `createdAt` | string | ISO timestamp. |
| `updatedAt` | string | ISO timestamp. |


## Authentication modes

- **`useAuthentication: true`** (recommended) — Frontline issues a 64-character access token on create. External callers must POST with `Authorization: Bearer <accessToken>`. The token is **only returned in the create response**; if you lose it, rotate the webhook.
- **`useAuthentication: false`** — anyone with the URL can POST. Treat the URL itself as a secret.


## Calling a webhook from the outside


```bash
curl -X POST "https://hooks.example.com/webhook/clx123incomingwebhook" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"123","status":"created"}'
```

The webhook persists the JSON body and exposes it to subscribed Workflow `WEBHOOK` trigger nodes, which can reference fields with the usual `{nodeId}` interpolation.

## Operations

| Verb | Path | Purpose |
|  --- | --- | --- |
| `POST` | `/public/v1/incoming-webhooks` | Create (USER key). Returns URL + token. |


The Public API currently only exposes the create endpoint. To list, rotate, or revoke existing webhooks, manage them from the Frontline dashboard.

## CLI


```bash
frontline incoming-webhooks create --name "CRM payload"
frontline incoming-webhooks create --name "CRM payload" --description "Receives contacts"
frontline incoming-webhooks create --name "Open endpoint" --no-authentication
```

Store the `accessToken` from the create response immediately — list/detail commands do not expose it.