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

# Update or Rotate the Secret on a Webhook Subscription

> PUT /v1/webhook-subscriptions/{id} — Updates the URL, name, event types, or active status of a webhook subscription. Requires webhooks.write scope.

This endpoint allows you to modify any aspect of an existing webhook subscription, including its target URL, display name, event type filters, and active status. You can also rotate the signing secret by supplying a new 64-character hex value in the `secret` field — when provided, the new secret is returned in the response and the old one is immediately invalidated. All fields in the request body are optional; only fields you include will be changed.

> [!NOTE]
>
> The destination `url` must belong to a domain listed in your tenant's `validDomains` configuration. Contact your Diameter account team to add new domains.

## Endpoint

```
PUT /v1/webhook-subscriptions/{id}
```

**Required scope:** `webhooks.write`

## Request Headers

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer {access_token}` |
| `x-idempotency-key` | Yes | A UUID v4 that makes this request safe to retry |
| `Content-Type` | Yes | `application/json` |

## Path Parameters

**id** `string` *required*

The UUID of the webhook subscription to update.

## Request Body

All fields are optional. Include only the fields you want to change.

**name** `string`

Updated friendly name for the subscription.

**url** `string`

Updated HTTPS endpoint URL. Must use `https://`, must not use redirects, and must belong to a domain in your tenant's `validDomains` list.

**eventTypes** `array`

Updated list of event type strings. Pass an empty array `[]` to reset the subscription to receive all events.

**isActive** `boolean`

Set to `false` to pause event delivery without deleting the subscription. Set to `true` to resume delivery.

**secret** `string`

A new 64-character hex string to use as the webhook signing secret. If provided, the old secret is immediately invalidated and the new secret is returned in the response. Generate one with: `openssl rand -hex 32`.

## Response — 200 OK

**id** `string`

UUID of the updated webhook subscription.

**name** `string`

Updated friendly name.

**url** `string`

Updated HTTPS endpoint URL.

**eventTypes** `array`

Updated list of subscribed event types.

**isActive** `boolean`

Current active status of the subscription.

**secret** `string`

The new signing secret. **Only present if `secret` was provided in the request body.** Store it immediately — it cannot be retrieved again after this response.

**createdAt** `string`

ISO 8601 creation timestamp (unchanged).

**updatedAt** `string`

ISO 8601 timestamp of this update.

## Examples

### Update the target URL and event types

```bash theme={null}
curl --request PUT \
  --url https://api.diameterpay.com/v1/webhook-subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: b5c7d9e1-f2a3-4b6c-8d0e-1f2a3b4c5d6e' \
  --data '{
    "url": "https://hooks.yourapp.com/diameter/payments-v2",
    "eventTypes": [
      "PAYMENT_WIRE_OUTBOUND_COMPLETED",
      "PAYMENT_WIRE_OUTBOUND_FAILED",
      "PAYMENT_WIRE_INBOUND_POSTED",
      "PAYMENT_ACH_RECEIVER_CREDIT_POSTED",
      "PAYMENT_ACH_RECEIVER_DEBIT_POSTED"
    ]
  }'
```

### Rotate the signing secret

```bash theme={null}
curl --request PUT \
  --url https://api.diameterpay.com/v1/webhook-subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: c6d8e0f2-a3b4-5c7d-9e1f-2a3b4c5d6e7f' \
  --data '{
    "secret": "b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2"
  }'
```

### Pause event delivery

```bash theme={null}
curl --request PUT \
  --url https://api.diameterpay.com/v1/webhook-subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: d7e9f1a3-b4c5-6d8e-0f2a-3b4c5d6e7f8a' \
  --data '{
    "isActive": false
  }'
```

### Response (with secret rotation)

```json theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Payment Notifications",
  "url": "https://hooks.yourapp.com/diameter/payments-v2",
  "eventTypes": [
    "PAYMENT_WIRE_OUTBOUND_COMPLETED",
    "PAYMENT_WIRE_OUTBOUND_FAILED",
    "PAYMENT_WIRE_INBOUND_POSTED",
    "PAYMENT_ACH_RECEIVER_CREDIT_POSTED",
    "PAYMENT_ACH_RECEIVER_DEBIT_POSTED"
  ],
  "isActive": true,
  "secret": "b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2",
  "createdAt": "2024-06-01T12:00:00.000Z",
  "updatedAt": "2024-06-05T14:22:00.000Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.