> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Webhook

> Update a webhook's URL, events, or secret

Update an existing webhook's URL, subscribed events, or channel-specific secret. The `channel` and `testMode` fields are immutable — to change them, remove and re-add the webhook.

```
POST /v1/actions/store/update-webhook
```

**Authentication:** API Key (owner or admin role required)

## Request Body

| Field    | Type           | Required | Description                                                                 |
| -------- | -------------- | -------- | --------------------------------------------------------------------------- |
| `id`     | string         | Yes      | Webhook UUID (returned from `add-webhook` or GraphQL `Store.storeWebhooks`) |
| `url`    | string         | No       | Replace target URL.                                                         |
| `events` | string\[]      | No       | Replace subscribed event types                                              |
| `secret` | string \| null | No       | Replace channel-specific credential. Pass `null` to clear.                  |

<Note>
  `channel` is permanent for a given webhook record — to switch channel, remove and re-add. URL changes are accepted as-is; merchant ensures the new URL matches the channel.
</Note>

## Example Request

<CodeGroup>
  ```typescript SDK theme={"system"}
  import { WaffoPancake } from "@waffo/pancake-ts";

  const client = new WaffoPancake({
    merchantId: process.env.WAFFO_MERCHANT_ID!,
    privateKey: process.env.WAFFO_PRIVATE_KEY!,
  });

  // Add more events to an existing webhook
  await client.webhooks.update({
    id: "11111111-2222-3333-4444-555555555555",
    events: ["order.completed", "refund.succeeded", "subscription.canceled"],
  });
  ```

  ```bash cURL theme={"system"}
  curl -X POST https://api.waffo.com/v1/actions/store/update-webhook \
    -H "Content-Type: application/json" \
    -H "X-Merchant-Id: $WAFFO_MERCHANT_ID" \
    -H "X-Signature: ..." \
    -d '{
      "id": "11111111-2222-3333-4444-555555555555",
      "events": ["order.completed", "refund.succeeded"]
    }'
  ```
</CodeGroup>

## Success Response (200)

Returns the updated webhook entity. Identical shape to [`add-webhook`](/api-reference/endpoints/webhooks/add-webhook#success-response-200).

## Response Fields

| Field       | Type           | Description                                                      |
| ----------- | -------------- | ---------------------------------------------------------------- |
| `id`        | string         | Webhook UUID                                                     |
| `storeId`   | string         | Owning store UUID                                                |
| `channel`   | string         | Webhook channel (immutable)                                      |
| `url`       | string         | Target webhook URL                                               |
| `events`    | string\[]      | Subscribed event types                                           |
| `testMode`  | boolean        | `true` for test transactions, `false` for production (immutable) |
| `secret`    | string \| null | Channel-specific credential, `null` if cleared                   |
| `createdAt` | string         | Creation timestamp (ISO 8601)                                    |
| `updatedAt` | string         | Last update timestamp (ISO 8601)                                 |

## Errors

> **Retry policy:** Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

| Status | `errors[0].message`                                | What it means                                                             | Recommended handling                                               |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| 400    | `Missing required field: id`                       | `id` was not provided                                                     | Fix the request body, resubmit                                     |
| 400    | `id must be a valid UUID`                          | `id` is not a valid UUID                                                  | Fix the `id`, resubmit                                             |
| 400    | `Invalid URL format`                               | `url` could not be parsed as a valid URL                                  | Fix the URL format (HTTPS, well-formed), resubmit                  |
| 400    | `events must be a string array`                    | `events` is not a JSON array of strings                                   | Send `events` as a string array (e.g. `["order.completed"]`)       |
| 400    | `secret must be a string or null`                  | `secret` is neither a string nor `null`                                   | Send a string value, or `null` to clear                            |
| 403    | `Not authorized to manage webhooks for this store` | The caller's merchant role on the owning store is not `owner` or `admin`  | Switch to an API Key whose merchant has the required role          |
| 404    | `Webhook not found`                                | No webhook matches the supplied `id` (or deleted by a concurrent request) | Verify the `id`; if just removed, re-list webhooks before retrying |
| 500    | `Internal server error`                            | Unexpected server-side failure                                            | Retry with exponential backoff (start 5s, max 3 attempts)          |