# Webhooks

## Retrieve a worker webhook

`client.Workers.Webhooks.Get(ctx, workerID) (*Webhook, error)`

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

- `workerID string`

### Returns

- `type Webhook struct{…}`

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

```go
package main

import (
  "context"
  "fmt"

  "github.com/ramensoft/handinger-go"
  "github.com/ramensoft/handinger-go/option"
)

func main() {
  client := handinger.NewClient(
    option.WithAPIKey("My API Key"),
  )
  webhook, err := client.Workers.Webhooks.Get(context.TODO(), "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", webhook.Token)
}
```

#### Response

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

## Update a worker webhook

`client.Workers.Webhooks.Update(ctx, workerID, body) (*Webhook, error)`

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

- `workerID string`

- `body WorkerWebhookUpdateParams`

  - `UpdateWebhook param.Field[UpdateWebhook]`

### Returns

- `type Webhook struct{…}`

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

```go
package main

import (
  "context"
  "fmt"

  "github.com/ramensoft/handinger-go"
  "github.com/ramensoft/handinger-go/option"
)

func main() {
  client := handinger.NewClient(
    option.WithAPIKey("My API Key"),
  )
  webhook, err := client.Workers.Webhooks.Update(
    context.TODO(),
    "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
    handinger.WorkerWebhookUpdateParams{
      UpdateWebhook: handinger.UpdateWebhookParam{
        URL: handinger.String("https://example.com/handinger-webhook"),
      },
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", webhook.Token)
}
```

#### Response

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

## Delete a worker webhook

`client.Workers.Webhooks.Delete(ctx, workerID) (*Webhook, error)`

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

- `workerID string`

### Returns

- `type Webhook struct{…}`

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

```go
package main

import (
  "context"
  "fmt"

  "github.com/ramensoft/handinger-go"
  "github.com/ramensoft/handinger-go/option"
)

func main() {
  client := handinger.NewClient(
    option.WithAPIKey("My API Key"),
  )
  webhook, err := client.Workers.Webhooks.Delete(context.TODO(), "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", webhook.Token)
}
```

#### Response

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

## Regenerate a worker webhook token

`client.Workers.Webhooks.RegenerateToken(ctx, workerID) (*Webhook, error)`

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

- `workerID string`

### Returns

- `type Webhook struct{…}`

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

```go
package main

import (
  "context"
  "fmt"

  "github.com/ramensoft/handinger-go"
  "github.com/ramensoft/handinger-go/option"
)

func main() {
  client := handinger.NewClient(
    option.WithAPIKey("My API Key"),
  )
  webhook, err := client.Workers.Webhooks.RegenerateToken(context.TODO(), "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", webhook.Token)
}
```

#### Response

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

## List worker webhook executions

`client.Workers.Webhooks.ListExecutions(ctx, workerID, query) (*WebhookExecutionList, error)`

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

- `workerID string`

- `query WorkerWebhookListExecutionsParams`

  - `Page param.Field[int64]`

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

### Returns

- `type WebhookExecutionList struct{…}`

  - `Logs []WebhookExecution`

    - `ID string`

    - `CreatedAt Time`

    - `DurationMs int64`

      Wall-clock time spent on the delivery attempt.

    - `ErrorMessage string`

      Failure reason when `requestStatus` is `error`.

    - `RequestStatus WebhookExecutionRequestStatus`

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

      - `const WebhookExecutionRequestStatusSuccess WebhookExecutionRequestStatus = "success"`

      - `const WebhookExecutionRequestStatusError WebhookExecutionRequestStatus = "error"`

    - `ResponseStatus int64`

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

    Current page number.

  - `PageCount int64`

    Total number of pages available.

  - `TotalCount int64`

    Total number of executions recorded.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/ramensoft/handinger-go"
  "github.com/ramensoft/handinger-go/option"
)

func main() {
  client := handinger.NewClient(
    option.WithAPIKey("My API Key"),
  )
  webhookExecutionList, err := client.Workers.Webhooks.ListExecutions(
    context.TODO(),
    "t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM",
    handinger.WorkerWebhookListExecutionsParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", webhookExecutionList.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

- `type UpdateWebhook struct{…}`

  - `URL string`

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

### Webhook

- `type Webhook struct{…}`

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

- `type WebhookExecution struct{…}`

  - `ID string`

  - `CreatedAt Time`

  - `DurationMs int64`

    Wall-clock time spent on the delivery attempt.

  - `ErrorMessage string`

    Failure reason when `requestStatus` is `error`.

  - `RequestStatus WebhookExecutionRequestStatus`

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

    - `const WebhookExecutionRequestStatusSuccess WebhookExecutionRequestStatus = "success"`

    - `const WebhookExecutionRequestStatusError WebhookExecutionRequestStatus = "error"`

  - `ResponseStatus int64`

    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

- `type WebhookExecutionList struct{…}`

  - `Logs []WebhookExecution`

    - `ID string`

    - `CreatedAt Time`

    - `DurationMs int64`

      Wall-clock time spent on the delivery attempt.

    - `ErrorMessage string`

      Failure reason when `requestStatus` is `error`.

    - `RequestStatus WebhookExecutionRequestStatus`

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

      - `const WebhookExecutionRequestStatusSuccess WebhookExecutionRequestStatus = "success"`

      - `const WebhookExecutionRequestStatusError WebhookExecutionRequestStatus = "error"`

    - `ResponseStatus int64`

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

    Current page number.

  - `PageCount int64`

    Total number of pages available.

  - `TotalCount int64`

    Total number of executions recorded.