# Webhooks

## Retrieve a worker webhook

**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.

### Path Parameters

- `workerId: string`

### 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

```http
curl https://handinger.com/api/workers/$WORKER_ID/webhook \
    -H "Authorization: Bearer $HANDINGER_API_KEY"
```

#### Response

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

## Update a worker webhook

**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.

### Path Parameters

- `workerId: string`

### Body Parameters

- `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

```http
curl https://handinger.com/api/workers/$WORKER_ID/webhook \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HANDINGER_API_KEY" \
    -d '{
          "url": "https://example.com/handinger-webhook"
        }'
```

#### Response

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

## Delete a worker webhook

**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.

### Path Parameters

- `workerId: string`

### 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

```http
curl https://handinger.com/api/workers/$WORKER_ID/webhook \
    -X DELETE \
    -H "Authorization: Bearer $HANDINGER_API_KEY"
```

#### Response

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

## Regenerate a worker webhook 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.

### Path Parameters

- `workerId: string`

### 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

```http
curl https://handinger.com/api/workers/$WORKER_ID/webhook/regenerate-token \
    -X POST \
    -H "Authorization: Bearer $HANDINGER_API_KEY"
```

#### Response

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

## List worker webhook 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.

### Path Parameters

- `workerId: string`

### Query Parameters

- `page: optional number`

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

### Returns

- `WebhookExecutionList 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

```http
curl https://handinger.com/api/workers/$WORKER_ID/webhook/executions \
    -H "Authorization: Bearer $HANDINGER_API_KEY"
```

#### 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

- `UpdateWebhook 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

- `WebhookExecution 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

- `WebhookExecutionList 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.