# Webhooks

## Retrieve a worker webhook

`$ handinger workers:webhooks retrieve`

**get** `/api/workers/{workerId}/webhook`

Retrieve the webhook URL and shared token configured for a worker. Both fields are `null` when no webhook is configured. Only the worker creator can read the webhook configuration.

### Parameters

- `--worker-id: string`

  Worker id returned by the create worker endpoint.

### Returns

- `webhook: object { token, url }`

  - `token: string`

    Shared secret sent in the `X-Handinger-Token` header on each delivery. `null` when no webhook is configured.

  - `url: string`

    HTTPS endpoint that receives webhook deliveries when a task completes. `null` when no webhook is configured.

### Example

```cli
handinger workers:webhooks retrieve \
  --api-key 'My API Key' \
  --worker-id t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM
```

#### Response

```json
{
  "token": "whk_01HZY31W2SZJ8MJ2FQTR3M1K9D",
  "url": "https://example.com/handinger-webhook"
}
```

## Update a worker webhook

`$ handinger workers:webhooks update`

**put** `/api/workers/{workerId}/webhook`

Set or replace the webhook URL for a worker. A fresh token is generated the first time a URL is set; subsequent updates keep the existing token. Pass `url: null` to clear the webhook (use the dedicated DELETE for the same effect). Only the worker creator can update the webhook.

### Parameters

- `--worker-id: string`

  Worker id returned by the create worker endpoint.

- `--url: string`

  HTTPS endpoint Handinger should POST to when a task finishes. Pass `null` to remove the webhook and clear its token.

### Returns

- `webhook: object { token, url }`

  - `token: string`

    Shared secret sent in the `X-Handinger-Token` header on each delivery. `null` when no webhook is configured.

  - `url: string`

    HTTPS endpoint that receives webhook deliveries when a task completes. `null` when no webhook is configured.

### Example

```cli
handinger workers:webhooks update \
  --api-key 'My API Key' \
  --worker-id t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM \
  --url https://example.com/handinger-webhook
```

#### Response

```json
{
  "token": "whk_01HZY31W2SZJ8MJ2FQTR3M1K9D",
  "url": "https://example.com/handinger-webhook"
}
```

## Delete a worker webhook

`$ handinger workers:webhooks delete`

**delete** `/api/workers/{workerId}/webhook`

Remove the webhook from a worker. Both `url` and `token` are cleared and no further deliveries are attempted. Only the worker creator can delete the webhook.

### Parameters

- `--worker-id: string`

  Worker id returned by the create worker endpoint.

### Returns

- `webhook: object { token, url }`

  - `token: string`

    Shared secret sent in the `X-Handinger-Token` header on each delivery. `null` when no webhook is configured.

  - `url: string`

    HTTPS endpoint that receives webhook deliveries when a task completes. `null` when no webhook is configured.

### Example

```cli
handinger workers:webhooks delete \
  --api-key 'My API Key' \
  --worker-id t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM
```

#### Response

```json
{
  "token": "whk_01HZY31W2SZJ8MJ2FQTR3M1K9D",
  "url": "https://example.com/handinger-webhook"
}
```

## Regenerate a worker webhook token

`$ handinger workers:webhooks regenerate-token`

**post** `/api/workers/{workerId}/webhook/regenerate-token`

Issue a new shared token for the webhook, invalidating the previous one. The webhook URL is preserved. Only the worker creator can regenerate the token.

### Parameters

- `--worker-id: string`

  Worker id returned by the create worker endpoint.

### Returns

- `webhook: object { token, url }`

  - `token: string`

    Shared secret sent in the `X-Handinger-Token` header on each delivery. `null` when no webhook is configured.

  - `url: string`

    HTTPS endpoint that receives webhook deliveries when a task completes. `null` when no webhook is configured.

### Example

```cli
handinger workers:webhooks regenerate-token \
  --api-key 'My API Key' \
  --worker-id t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM
```

#### Response

```json
{
  "token": "whk_01HZY31W2SZJ8MJ2FQTR3M1K9D",
  "url": "https://example.com/handinger-webhook"
}
```

## List worker webhook executions

`$ handinger workers:webhooks list-executions`

**get** `/api/workers/{workerId}/webhook/executions`

List recent webhook delivery attempts for a worker, newest first, paginated 50 per page. Only the worker creator can read execution history.

### Parameters

- `--worker-id: string`

  Worker id returned by the create worker endpoint.

- `--page: optional number`

  Page number (1-indexed). Defaults to 1.

### Returns

- `webhook_execution_list: object { logs, page, pageCount, totalCount }`

  - `logs: array of WebhookExecution`

    - `id: string`

    - `createdAt: string`

    - `durationMs: number`

      Wall-clock time spent on the delivery attempt.

    - `errorMessage: string`

      Failure reason when `requestStatus` is `error`.

    - `requestStatus: "success" or "error"`

      `success` when the endpoint returned a 2xx response, `error` otherwise.

      - `"success"`

      - `"error"`

    - `responseStatus: number`

      HTTP status returned by the endpoint, when reachable.

    - `taskId: string`

      Task that triggered the delivery, when available.

    - `taskTitle: string`

      Title of the originating task, when available.

    - `url: string`

      Endpoint Handinger attempted to deliver to.

    - `workerId: string`

  - `page: number`

    Current page number.

  - `pageCount: number`

    Total number of pages available.

  - `totalCount: number`

    Total number of executions recorded.

### Example

```cli
handinger workers:webhooks list-executions \
  --api-key 'My API Key' \
  --worker-id t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM
```

#### Response

```json
{
  "logs": [
    {
      "id": "whe_01HZY31W2SZJ8MJ2FQTR3M1K9D",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "durationMs": 0,
      "errorMessage": "errorMessage",
      "requestStatus": "success",
      "responseStatus": 0,
      "taskId": "taskId",
      "taskTitle": "taskTitle",
      "url": "url",
      "workerId": "workerId"
    }
  ],
  "page": 0,
  "pageCount": 0,
  "totalCount": 0
}
```

## Domain Types

### Update Webhook

- `update_webhook: object { url }`

  - `url: string`

    HTTPS endpoint Handinger should POST to when a task finishes. Pass `null` to remove the webhook and clear its token.

### Webhook

- `webhook: object { token, url }`

  - `token: string`

    Shared secret sent in the `X-Handinger-Token` header on each delivery. `null` when no webhook is configured.

  - `url: string`

    HTTPS endpoint that receives webhook deliveries when a task completes. `null` when no webhook is configured.

### Webhook Execution

- `webhook_execution: object { id, createdAt, durationMs, 7 more }`

  - `id: string`

  - `createdAt: string`

  - `durationMs: number`

    Wall-clock time spent on the delivery attempt.

  - `errorMessage: string`

    Failure reason when `requestStatus` is `error`.

  - `requestStatus: "success" or "error"`

    `success` when the endpoint returned a 2xx response, `error` otherwise.

    - `"success"`

    - `"error"`

  - `responseStatus: number`

    HTTP status returned by the endpoint, when reachable.

  - `taskId: string`

    Task that triggered the delivery, when available.

  - `taskTitle: string`

    Title of the originating task, when available.

  - `url: string`

    Endpoint Handinger attempted to deliver to.

  - `workerId: string`

### Webhook Execution List

- `webhook_execution_list: object { logs, page, pageCount, totalCount }`

  - `logs: array of WebhookExecution`

    - `id: string`

    - `createdAt: string`

    - `durationMs: number`

      Wall-clock time spent on the delivery attempt.

    - `errorMessage: string`

      Failure reason when `requestStatus` is `error`.

    - `requestStatus: "success" or "error"`

      `success` when the endpoint returned a 2xx response, `error` otherwise.

      - `"success"`

      - `"error"`

    - `responseStatus: number`

      HTTP status returned by the endpoint, when reachable.

    - `taskId: string`

      Task that triggered the delivery, when available.

    - `taskTitle: string`

      Title of the originating task, when available.

    - `url: string`

      Endpoint Handinger attempted to deliver to.

    - `workerId: string`

  - `page: number`

    Current page number.

  - `pageCount: number`

    Total number of pages available.

  - `totalCount: number`

    Total number of executions recorded.