# Webhooks

## Retrieve a worker webhook

`workers.webhooks.retrieve(worker_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: String`

### Returns

- `class Webhook`

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

```ruby
require "handinger"

handinger = Handinger::Client.new(api_key: "My API Key")

webhook = handinger.workers.webhooks.retrieve("t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM")

puts(webhook)
```

#### Response

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

## Update a worker webhook

`workers.webhooks.update(worker_id, **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: String`

- `url: String`

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

### Returns

- `class Webhook`

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

```ruby
require "handinger"

handinger = Handinger::Client.new(api_key: "My API Key")

webhook = handinger.workers.webhooks.update(
  "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
  url: "https://example.com/handinger-webhook"
)

puts(webhook)
```

#### Response

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

## Delete a worker webhook

`workers.webhooks.delete(worker_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: String`

### Returns

- `class Webhook`

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

```ruby
require "handinger"

handinger = Handinger::Client.new(api_key: "My API Key")

webhook = handinger.workers.webhooks.delete("t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM")

puts(webhook)
```

#### Response

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

## Regenerate a worker webhook token

`workers.webhooks.regenerate_token(worker_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: String`

### Returns

- `class Webhook`

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

```ruby
require "handinger"

handinger = Handinger::Client.new(api_key: "My API Key")

webhook = handinger.workers.webhooks.regenerate_token("t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM")

puts(webhook)
```

#### Response

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

## List worker webhook executions

`workers.webhooks.list_executions(worker_id, **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: String`

- `page: Integer`

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

### Returns

- `class WebhookExecutionList`

  - `logs: Array[WebhookExecution]`

    - `id: String`

    - `created_at: Time`

    - `duration_ms: Integer`

      Wall-clock time spent on the delivery attempt.

    - `error_message: String`

      Failure reason when `requestStatus` is `error`.

    - `request_status: :success | :error`

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

      - `:success`

      - `:error`

    - `response_status: Integer`

      HTTP status returned by the endpoint, when reachable.

    - `task_id: String`

      Task that triggered the delivery, when available.

    - `task_title: String`

      Title of the originating task, when available.

    - `url: String`

      Endpoint Handinger attempted to deliver to.

    - `worker_id: String`

  - `page: Integer`

    Current page number.

  - `page_count: Integer`

    Total number of pages available.

  - `total_count: Integer`

    Total number of executions recorded.

### Example

```ruby
require "handinger"

handinger = Handinger::Client.new(api_key: "My API Key")

webhook_execution_list = handinger.workers.webhooks.list_executions("t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM")

puts(webhook_execution_list)
```

#### 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: String`

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

### Webhook

- `class Webhook`

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

- `class WebhookExecution`

  - `id: String`

  - `created_at: Time`

  - `duration_ms: Integer`

    Wall-clock time spent on the delivery attempt.

  - `error_message: String`

    Failure reason when `requestStatus` is `error`.

  - `request_status: :success | :error`

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

    - `:success`

    - `:error`

  - `response_status: Integer`

    HTTP status returned by the endpoint, when reachable.

  - `task_id: String`

    Task that triggered the delivery, when available.

  - `task_title: String`

    Title of the originating task, when available.

  - `url: String`

    Endpoint Handinger attempted to deliver to.

  - `worker_id: String`

### Webhook Execution List

- `class WebhookExecutionList`

  - `logs: Array[WebhookExecution]`

    - `id: String`

    - `created_at: Time`

    - `duration_ms: Integer`

      Wall-clock time spent on the delivery attempt.

    - `error_message: String`

      Failure reason when `requestStatus` is `error`.

    - `request_status: :success | :error`

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

      - `:success`

      - `:error`

    - `response_status: Integer`

      HTTP status returned by the endpoint, when reachable.

    - `task_id: String`

      Task that triggered the delivery, when available.

    - `task_title: String`

      Title of the originating task, when available.

    - `url: String`

      Endpoint Handinger attempted to deliver to.

    - `worker_id: String`

  - `page: Integer`

    Current page number.

  - `page_count: Integer`

    Total number of pages available.

  - `total_count: Integer`

    Total number of executions recorded.