# Webhooks

## Retrieve a worker webhook

`workers.webhooks.retrieve(strworker_id)  -> 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.

### Parameters

- `worker_id: str`

### Returns

- `class Webhook: …`

  - `token: Optional[str]`

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

  - `url: Optional[str]`

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

### Example

```python
import os
from handinger import Handinger

client = Handinger(
    api_key=os.environ.get("HANDINGER_API_KEY"),  # This is the default and can be omitted
)
webhook = client.workers.webhooks.retrieve(
    "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
)
print(webhook.token)
```

#### Response

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

## Update a worker webhook

`workers.webhooks.update(strworker_id, WebhookUpdateParams**kwargs)  -> 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.

### Parameters

- `worker_id: str`

- `url: Optional[str]`

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

### Returns

- `class Webhook: …`

  - `token: Optional[str]`

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

  - `url: Optional[str]`

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

### Example

```python
import os
from handinger import Handinger

client = Handinger(
    api_key=os.environ.get("HANDINGER_API_KEY"),  # This is the default and can be omitted
)
webhook = client.workers.webhooks.update(
    worker_id="t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
    url="https://example.com/handinger-webhook",
)
print(webhook.token)
```

#### Response

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

## Delete a worker webhook

`workers.webhooks.delete(strworker_id)  -> 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.

### Parameters

- `worker_id: str`

### Returns

- `class Webhook: …`

  - `token: Optional[str]`

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

  - `url: Optional[str]`

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

### Example

```python
import os
from handinger import Handinger

client = Handinger(
    api_key=os.environ.get("HANDINGER_API_KEY"),  # This is the default and can be omitted
)
webhook = client.workers.webhooks.delete(
    "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
)
print(webhook.token)
```

#### Response

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

## Regenerate a worker webhook token

`workers.webhooks.regenerate_token(strworker_id)  -> Webhook`

**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: str`

### Returns

- `class Webhook: …`

  - `token: Optional[str]`

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

  - `url: Optional[str]`

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

### Example

```python
import os
from handinger import Handinger

client = Handinger(
    api_key=os.environ.get("HANDINGER_API_KEY"),  # This is the default and can be omitted
)
webhook = client.workers.webhooks.regenerate_token(
    "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
)
print(webhook.token)
```

#### Response

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

## List worker webhook executions

`workers.webhooks.list_executions(strworker_id, WebhookListExecutionsParams**kwargs)  -> WebhookExecutionList`

**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: str`

- `page: Optional[int]`

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

### Returns

- `class WebhookExecutionList: …`

  - `logs: List[WebhookExecution]`

    - `id: str`

    - `created_at: datetime`

    - `duration_ms: int`

      Wall-clock time spent on the delivery attempt.

    - `error_message: Optional[str]`

      Failure reason when `requestStatus` is `error`.

    - `request_status: Literal["success", "error"]`

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

      - `"success"`

      - `"error"`

    - `response_status: Optional[int]`

      HTTP status returned by the endpoint, when reachable.

    - `task_id: Optional[str]`

      Task that triggered the delivery, when available.

    - `task_title: Optional[str]`

      Title of the originating task, when available.

    - `url: str`

      Endpoint Handinger attempted to deliver to.

    - `worker_id: str`

  - `page: int`

    Current page number.

  - `page_count: int`

    Total number of pages available.

  - `total_count: int`

    Total number of executions recorded.

### Example

```python
import os
from handinger import Handinger

client = Handinger(
    api_key=os.environ.get("HANDINGER_API_KEY"),  # This is the default and can be omitted
)
webhook_execution_list = client.workers.webhooks.list_executions(
    worker_id="t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
)
print(webhook_execution_list.logs)
```

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

- `class UpdateWebhook: …`

  - `url: Optional[str]`

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

### Webhook

- `class Webhook: …`

  - `token: Optional[str]`

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

  - `url: Optional[str]`

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

### Webhook Execution

- `class WebhookExecution: …`

  - `id: str`

  - `created_at: datetime`

  - `duration_ms: int`

    Wall-clock time spent on the delivery attempt.

  - `error_message: Optional[str]`

    Failure reason when `requestStatus` is `error`.

  - `request_status: Literal["success", "error"]`

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

    - `"success"`

    - `"error"`

  - `response_status: Optional[int]`

    HTTP status returned by the endpoint, when reachable.

  - `task_id: Optional[str]`

    Task that triggered the delivery, when available.

  - `task_title: Optional[str]`

    Title of the originating task, when available.

  - `url: str`

    Endpoint Handinger attempted to deliver to.

  - `worker_id: str`

### Webhook Execution List

- `class WebhookExecutionList: …`

  - `logs: List[WebhookExecution]`

    - `id: str`

    - `created_at: datetime`

    - `duration_ms: int`

      Wall-clock time spent on the delivery attempt.

    - `error_message: Optional[str]`

      Failure reason when `requestStatus` is `error`.

    - `request_status: Literal["success", "error"]`

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

      - `"success"`

      - `"error"`

    - `response_status: Optional[int]`

      HTTP status returned by the endpoint, when reachable.

    - `task_id: Optional[str]`

      Task that triggered the delivery, when available.

    - `task_title: Optional[str]`

      Title of the originating task, when available.

    - `url: str`

      Endpoint Handinger attempted to deliver to.

    - `worker_id: str`

  - `page: int`

    Current page number.

  - `page_count: int`

    Total number of pages available.

  - `total_count: int`

    Total number of executions recorded.