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

# Update Webhook Endpoint

> Update an existing webhook configuration

# Update Webhook Endpoint

PUT [https://api.baanx.com/v1/webhooks/\{id}](https://api.baanx.com/v1/webhooks/\{id})
Updates an existing webhook configuration.

## Overview

All fields are optional — only provide the fields you want to change. The response returns the full updated webhook configuration with a masked API key.

<Note>
  To change the API key used for signature verification, use the [Rotate Key](/api-reference/webhooks/rotate-key) endpoint instead.
</Note>

## Authentication

This endpoint requires authentication via Bearer token:

```bash theme={null} theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Path Parameters

<ParamField path="id" type="string (UUID)" required>
  Unique identifier of the webhook configuration to update
</ParamField>

### Body

All body fields are optional. Only include the fields you wish to update.

<ParamField body="name" type="string">
  New human-readable name for the webhook (max 255 characters)
</ParamField>

<ParamField body="url" type="string">
  New HTTPS endpoint URL. Must use HTTPS.
</ParamField>

<ParamField body="event_types" type="array">
  New list of event type strings. Replaces the existing list. Must contain at least one item if provided.
</ParamField>

<ParamField body="is_active" type="boolean">
  Set to `true` to activate or `false` to deactivate the webhook
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata to attach to the webhook. Replaces existing metadata.
</ParamField>

### Request Examples

<CodeGroup>
  ```bash cURL - Enable Webhook theme={null} theme={null}
  curl -X PUT https://api.baanx.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "is_active": true
    }'
  ```

  ```bash cURL - Update URL theme={null} theme={null}
  curl -X PUT https://api.baanx.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://api.partner.com/webhooks/v2/events"
    }'
  ```

  ```javascript JavaScript theme={null} theme={null}
  const webhookId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(`https://api.baanx.com/v1/webhooks/${webhookId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Updated Webhook Name',
      url: 'https://api.partner.com/webhooks/new',
      event_types: ['kyc.status.changed', 'card.activated'],
      is_active: true
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null} theme={null}
  import requests

  webhook_id = "550e8400-e29b-41d4-a716-446655440000"
  url = f"https://api.baanx.com/v1/webhooks/{webhook_id}"
  headers = {
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "is_active": True
  }

  response = requests.put(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```typescript TypeScript theme={null} theme={null}
  interface UpdateWebhookRequest {
    name?: string;
    url?: string;
    event_types?: string[];
    is_active?: boolean;
    metadata?: Record<string, unknown>;
  }

  const updateWebhook = async (webhookId: string, updates: UpdateWebhookRequest) => {
    const response = await fetch(`https://api.baanx.com/v1/webhooks/${webhookId}`, {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  };
  ```
</CodeGroup>

## Response

### 200 Success

<ResponseField name="success" type="boolean">
  Indicates the webhook was updated successfully
</ResponseField>

<ResponseField name="data" type="object">
  The full updated webhook configuration with masked API key. See [Get Webhook](/api-reference/webhooks/get-webhook) for field descriptions.
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null} theme={null}
  {
    "success": true,
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant": "partner-name",
      "name": "Updated Webhook Name",
      "url": "https://api.partner.com/webhooks/new",
      "apiKey": "whk_****...****5678",
      "eventTypes": ["kyc.status.changed", "card.activated"],
      "isActive": true,
      "metadata": {},
      "createdAt": "2025-12-29T10:00:00.000Z",
      "updatedAt": "2025-12-29T12:30:00.000Z"
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 - Validation Error theme={null} theme={null}
  {
    "message": "url must be an HTTPS URL"
  }
  ```

  ```json 401 - Unauthorized theme={null} theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Forbidden theme={null} theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 404 - Not Found theme={null} theme={null}
  {
    "message": "Webhook config not found"
  }
  ```

  ```json 503 - Service Unavailable theme={null} theme={null}
  {
    "message": "Notification service is not configured for this environment"
  }
  ```
</ResponseExample>

## Related Endpoints

* `GET /v1/webhooks/{id}` - Get current webhook configuration
* `POST /v1/webhooks/{id}/rotate-key` - Rotate the signing API key
* `DELETE /v1/webhooks/{id}` - Delete this webhook