---
title: "Update Webhook"
method: PUT
path: "/api/v2/webhooks/{webhook_id}"
tags: ["Webhooks"]
---

# Update Webhook

`PUT /api/v2/webhooks/{webhook_id}`

## Request

- Base URL: `https://stream-app-service.streampay.sa`
- URL: `https://stream-app-service.streampay.sa/api/v2/webhooks/{webhook_id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Update a webhook's URL, name, secret key, subscribed events, or enabled state.

Fields sent as `null` keep their current value. `subscriptions`, when sent, replaces the whole list.

## Path parameters

- `webhook_id` string, uuid, required

## Request body

- UpdateWebhookRequest
  - `url` string, uri, nullable: HTTPS URL that receives event notifications. It must use port 443 and resolve to a public address. Omit or send `null` to keep the current URL.
  - `enabled` boolean, nullable: Whether events are delivered to this webhook. Omit or send `null` to keep the current value.
  - `secret_key` string, nullable: Secret used to sign each delivery. Every request carries an `X-Webhook-Signature: t=<timestamp>,v1=<signature>` header, where `<signature>` is the hex HMAC-SHA256 of `<timestamp>.<raw request body>` keyed with this secret. Omit or send `null` to keep the current secret.
  - `name` string, nullable: Label to tell webhooks apart. Omit or send `null` to keep the current name.
  - `subscriptions` WebhookEventType[], nullable: Events this webhook receives. `GET /v2/webhooks/events` lists the available events. Replaces the whole list. Omit or send `null` to keep the current events.

## Response `200`

Successful Response

- WebhookResponse
  - `created_by_type` 'USER' | 'API_KEY' | 'CONNECTED_APP' | 'CUSTOMER' | 'ADMIN_PANEL' | 'OPS' | 'SYSTEM' | 'UNKNOWN'
  - `created_by_id` string, uuid, nullable: Unique identifier (UUID) of the user who created the object. For API_KEY it is the key's owner, for CONNECTED_APP the user who connected the app; a placeholder user for CUSTOMER, ADMIN_PANEL, OPS and SYSTEM; null when UNKNOWN.
  - `id` string, uuid: Unique identifier (UUID) of the webhook.
  - `organization_id` string, uuid: Unique identifier (UUID) of the organization.
  - `url` string, uri: HTTPS URL that receives event notifications.
  - `name` string, nullable: Label to tell webhooks apart.
  - `enabled` boolean: Whether events are delivered to this webhook.
  - `health_status` 'ENABLED' | 'WARNING' | 'DISABLED' | 'BLOCKED': Computed health status for merchant webhook list UI.
  - `created_by` string, uuid: ID of the user who created the webhook. The same as `created_by_id`.
  - `event_subscriptions` WebhookEventSubscriptionResponse[]: Events this webhook is subscribed to.
    - `event_type` 'PAYMENT_SUCCEEDED' | 'PAYMENT_FAILED' | 'PAYMENT_CANCELED' | 'PAYMENT_REFUNDED' | 'PAYMENT_MARKED_AS_PAID' | 'INVOICE_CREATED' | 'INVOICE_SENT' | 'INVOICE_ACCEPTED' | 'INVOICE_REJECTED' | 'INVOICE_COMPLETED' | 'INVOICE_CANCELED' | 'INVOICE_UPDATED' | 'SUBSCRIPTION_CREATED' | 'SUBSCRIPTION_ACTIVATED' | 'SUBSCRIPTION_INACTIVATED' | 'SUBSCRIPTION_CANCELED' | 'SUBSCRIPTION_FROZEN' | 'SUBSCRIPTION_CYCLE_RENEWED_SUCCESSFULLY' | 'SUBSCRIPTION_CYCLE_RENEWAL_FAILED' | 'SUBSCRIPTION_CANCEL_AT_PERIOD_END' | 'SUBSCRIPTION_FREEZE_NOW' | 'SUBSCRIPTION_FREEZE_FUTURE' | 'SUBSCRIPTION_UNFREEZE_NOW' | 'SUBSCRIPTION_UNFREEZE_FUTURE' | 'SUBSCRIPTION_FREEZE_CANCEL' | 'PAYMENT_LINK_PAY_ATTEMPT_FAILED' | 'SUBSCRIPTION_PLAN_CHANGE_SCHEDULED' | 'SUBSCRIPTION_PLAN_CHANGE_CANCELED' | 'SUBSCRIPTION_PLAN_CHANGED' | 'SUBSCRIPTION_PLAN_CHANGE_INVOICE_REISSUED' | 'SUBSCRIPTION_PLAN_UPDATED' | 'PAYMENT_PARTIALLY_REFUNDED' | 'METERED_SUBSCRIPTION_CANCELED' | 'INVOICE_EXPIRED' | 'PAYMENT_EXPIRED': Event types that can trigger webhooks.
    - `enabled` boolean: Whether this event is delivered.

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-05** `9c73cbd109e4`: 3 info
  - added the optional property `created_by_id` to the response with the `200` status
  - added the optional property `created_by_type` to the response with the `200` status
  - added the optional property `organization_id` to the response with the `200` status
- **2026-11-05** `39327fe3e24a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/streampay/apis/stream-app/changes/api/v2/webhooks/:webhook_id/put.md)

---

[API](https://skmtc.dev/streampay/apis/stream-app.md) - [All operations](https://skmtc.dev/streampay/apis/stream-app/llms.txt) - [OpenAPI document](https://skmtc.dev/streampay/apis/stream-app/revisions/9c73cbd109e4?raw)