# Update a webhook endpoint

Source: https://docs.coderhelm.com/api/reference/webhook-endpoints/update-webhook-endpoint

`PUT /api/webhooks/endpoints/{endpoint_id}`

Changes the address, description, events, or turns the endpoint on or off. Fields left out keep their value. Turning an endpoint back on starts its failure count again; events missed while it was off are not sent by themselves (replay them).

## Authentication

A team API key: `Authorization: Bearer chk_...`. The key needs the `webhooks` scope. See [Authentication](https://docs.coderhelm.com/api/authentication).

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `endpoint_id` | string | yes | The endpoint's id. |

## Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string or null | no | A new note. |
| `enabled` | boolean or null | no | Turning an endpoint back on starts its failure count again. |
| `events` | array of string or null | no | The new subscription list, or `["*"]`. |
| `url` | string or null | no | A new `https://` address. |

## Responses

### 200

The endpoint as saved.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes | When it was added. |
| `created_by` | string | yes | Who added it. |
| `description` | string | yes | A note for people: what the endpoint is for. |
| `disabled_reason` | string | yes | Why it's off: `manual` (turned off by a person) or `failing` (turned off by CoderHelm after 5 days of failed deliveries). Empty while on. |
| `enabled` | boolean | yes | Off: nothing is sent (tests still are). |
| `events` | array of string | yes | Event types it receives; `["*"]` is every event, including types added later. |
| `failing_since` | string or null | no | The first failed delivery since the last success. |
| `id` | string | yes | `ep_` and a ULID. |
| `last_failure_at` | string or null | no | The last failed attempt. |
| `last_success_at` | string or null | no | The last delivered attempt. |
| `previous_secret_expires_at` | string or null | no | While a rotated-out secret still signs too, when it stops. |
| `secret_hint` | string | yes | The last characters of the signing secret. |
| `updated_at` | string | yes | When it last changed. |
| `url` | string | yes | Where events are POSTed. Always `https://`. |

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.

### 400

A field was refused; `field` names which.

### 401

The key is missing, malformed, revoked or expired, or the person who made it left the team.

### 403

The key lacks the scope this endpoint needs (`missing_scope`).

### 404

No such endpoint on this team.

### 429

Over the key's rate limit (`rate_limited`), or, for endpoints that start work, over the team's monthly token limit (`token_limit_reached`).

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Retry-After`.

### 500

Something failed on CoderHelm's side. Safe to retry reads.

## Example request

cURL:

```bash
curl -X PUT 'https://api.coderhelm.com/api/webhooks/endpoints/ep_01jbendpt4a7b0c3d6e9f2g5h8' \
  -H "Authorization: Bearer $CODERHELM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Deploy bot (staging)",
  "enabled": true,
  "events": [
    "*"
  ],
  "url": "https://hooks.example.com/coderhelm/v2"
}'
```

TypeScript:

```ts
const res = await fetch("https://api.coderhelm.com/api/webhooks/endpoints/ep_01jbendpt4a7b0c3d6e9f2g5h8", {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CODERHELM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "description": "Deploy bot (staging)",
      "enabled": true,
      "events": [
        "*"
      ],
      "url": "https://hooks.example.com/coderhelm/v2"
    }),
});
if (!res.ok) {
  const { error, code } = await res.json();
  throw new Error(`${res.status} ${code}: ${error}`);
}
const data = await res.json();
```

Python:

```python
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CODERHELM_API_KEY']}",
}
body = {
    "description": "Deploy bot (staging)",
    "enabled": True,
    "events": [
        "*",
    ],
    "url": "https://hooks.example.com/coderhelm/v2",
}
res = requests.request("PUT", "https://api.coderhelm.com/api/webhooks/endpoints/ep_01jbendpt4a7b0c3d6e9f2g5h8", headers=headers, json=body)
if not res.ok:
    raise RuntimeError(f"{res.status_code}: {res.json().get('error')}")
data = res.json()
```

## Example response

```json
{
  "created_at": "2026-10-20T09:00:00Z",
  "created_by": "lead@example.com",
  "description": "Deploy bot",
  "disabled_reason": "",
  "enabled": true,
  "events": [
    "run.completed",
    "run.failed"
  ],
  "failing_since": null,
  "id": "ep_01jbendpt4a7b0c3d6e9f2g5h8",
  "last_failure_at": "2026-10-25T08:02:11.004Z",
  "last_success_at": "2026-10-26T14:31:48.120Z",
  "previous_secret_expires_at": "2026-10-27T09:00:00Z",
  "secret_hint": "whsec_…Q2c=",
  "updated_at": "2026-10-20T09:00:00Z",
  "url": "https://hooks.example.com/coderhelm"
}
```