Update or Rotate the Secret on a Webhook Subscription

PUT /v1/webhook-subscriptions/ — 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.

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

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

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

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)

{
  "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"
}