# Webhooks

Register and manage your outbound webhook programmatically: set the destination, switch payload mode, delete, and inspect or replay recent deliveries.

Register and manage the webhook that receives [workflow and account events](/docs/webhooks). For general Admin API information, see the [Admin overview](/docs/admin-overview). A client may hold one active webhook at a time.

## webhook.set

Register the webhook. Enforces a maximum of one active webhook per client. There is no update endpoint – to change the destination, delete the webhook and set a new one.

```bash
curl -X POST https://api.linkedapi.io/admin/webhook.set \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{
    "url": "https://example.com/hooks/linkedapi",
    "payloadMode": "fat"
  }'
```

**Body:**

- `url` – HTTPS endpoint that will receive deliveries. Required.
- `payloadMode` – `fat` (default) or `thin`. See [payload modes](/docs/webhooks#payload-modes). Optional.

**Response:**

```json
{
  "success": true,
  "result": {
    "webhook": {
      "id": "whs-...",
      "url": "https://example.com/hooks/linkedapi",
      "payloadMode": "fat",
      "isActive": true,
      "createdAt": "2026-06-25T12:00:00.000Z"
    }
  }
}
```

- `id` – webhook identifier, used by the other endpoints.
- `url` – the registered destination.
- `payloadMode` – current payload mode.
- `isActive` – whether the webhook is active.
- `createdAt` – ISO 8601 timestamp.

> A `url` that is a bare IP address in a private or internal range is rejected. Deliveries are only ever sent to public addresses.

## webhook.get

List the active webhook for this client. Returns an array with at most one entry.

```bash
curl -X POST https://api.linkedapi.io/admin/webhook.get \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"
```

**Response:**

```json
{
  "success": true,
  "result": {
    "webhooks": [
      {
        "id": "whs-...",
        "url": "https://example.com/hooks/linkedapi",
        "payloadMode": "fat",
        "isActive": true,
        "createdAt": "2026-06-25T12:00:00.000Z"
      }
    ]
  }
}
```

## webhook.setPayloadMode

Switch the [payload mode](/docs/webhooks#payload-modes) between `fat` and `thin`.

```bash
curl -X POST https://api.linkedapi.io/admin/webhook.setPayloadMode \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-...", "payloadMode": "thin" }'
```

**Body:**

- `id` – webhook identifier. Required.
- `payloadMode` – `fat` or `thin`. Required.

## webhook.delete

Delete the webhook. This is a soft delete: the delivery history is preserved and any still-pending deliveries are dropped. Because only active webhooks count toward the one-per-client limit, you can register a fresh webhook afterwards.

```bash
curl -X POST https://api.linkedapi.io/admin/webhook.delete \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "id": "whs-..." }'
```

**Body:**

- `id` – webhook identifier. Required.

## webhook.deliveries

Return the most recent deliveries (newest first) as a debug feed – useful for confirming an endpoint is receiving and acknowledging events.

```bash
curl -X POST https://api.linkedapi.io/admin/webhook.deliveries \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"
```

**Response:**

```json
{
  "success": true,
  "result": {
    "deliveries": [
      {
        "id": "whd-...",
        "eventType": "workflow.completed",
        "eventId": "workflow.completed:wf-...",
        "status": "success",
        "attempts": 1,
        "responseStatusCode": 200,
        "lastError": null,
        "createdAt": "2026-06-25T12:00:00.000Z",
        "updatedAt": "2026-06-25T12:00:01.000Z"
      }
    ]
  }
}
```

- `id` – delivery identifier, passed to `webhook.replayDelivery`.
- `eventType` – the event `type` that was delivered.
- `eventId` – the envelope `id` of the delivered event.
- `status` – `pending`, `delivering`, `success`, or `failed`.
- `attempts` – delivery attempts made so far.
- `responseStatusCode` – HTTP status your endpoint returned on the last attempt, or `null`.
- `lastError` – error text from the last failed attempt, or `null`.
- `createdAt` / `updatedAt` – ISO 8601 timestamps.

## webhook.replayDelivery

Re-arm an already-settled (`success` or `failed`) delivery for redelivery. The same `eventId` is reused, so consumer-side deduplication still applies – this is a true redelivery, not a new event.

```bash
curl -X POST https://api.linkedapi.io/admin/webhook.replayDelivery \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{ "deliveryId": "whd-..." }'
```

**Body:**

- `deliveryId` – delivery identifier from `webhook.deliveries`. Required.

## webhook.sendTest

Emit a synthetic `webhook.test` event to the active webhook through the normal delivery path. Its `data` carries a single `message` field. Use it to verify a freshly registered endpoint without waiting for a real event.

```bash
curl -X POST https://api.linkedapi.io/admin/webhook.sendTest \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"
```