Skip to main content
Partially updates an existing webhook subscription. This is a patch-style operation — only fields you include in the request body are modified; any field you omit (or send as null) retains its current value. At least one field must be provided. You can use this endpoint to change the callback URL, update the event list, toggle the subscription on or off, or update the description.
The source API uses POST (not PUT) for this update operation. Use the path POST /public/webhook/subscription/{SubscriptionId}.

​
Request

POST /public/webhook/subscription/{SubscriptionId}

​
Headers

​
Accept
string
required
Must be application/json.
​
Content-Type
string
required
Must be application/x-www-form-urlencoded.
​
X-MSS-API-APPID
string
required
Your API Application Key.
​
X-MSS-API-USERKEY
string
required
Your User API Key.
​
X-MSS-CUSTOM-DATE
string
required
Current UTC timestamp in RFC 7231 format (e.g. Mon, 06 Apr 2026 00:22:19 GMT).
​
X-MSS-SIGNATURE
string
required
HMAC-SHA256 signature of the canonical request, Base64-encoded.

​
Path Parameters

​
SubscriptionId
integer
required
Numeric ID of the webhook subscription to update. Must belong to the authenticated account; returns 400 if not found.

​
Body Parameters

​
Url
string
New HTTPS callback URL. Must use https:// and resolve to a publicly routable host. Omit to keep the current URL.
​
Events
string
Comma-separated list of event type strings to replace the current event list. Omit to keep the existing events. See the Webhook Events reference for available types.
​
Enabled
boolean
Set true to enable the subscription or false to disable it. Disabled subscriptions do not receive event deliveries. Omit to keep the current state.
​
Description
string
Human-readable label for the subscription. Omit to keep the current description.

​
Response

​
200 Success

Returns the full updated subscription object.
​
subscriptionId
integer
required
Unique numeric identifier of the subscription.
​
url
string
required
Current HTTPS callback URL.
​
description
string
Current description label.
​
enabled
boolean
required
Whether the subscription is currently active.
​
secretKey
string
required
HMAC secret for verifying webhook deliveries. Unchanged by update operations.
​
events
array
required
Current list of subscribed event type strings.

​
Error Codes

CodeMeaning
400Validation failed. Common causes: subscription not found or does not belong to this account, URL is not HTTPS or resolves to a private address, unrecognized event names, or no fields were provided.
401HMAC signature validation failed or credentials are invalid.
402An active Portal.io subscription is required to use this endpoint.
403Your user account does not have permission for this action.

​
Example

curl -i -X POST \
  'https://api.portal.io/public/webhook/subscription/42' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-MSS-API-APPID: YOUR_APP_ID' \
  -H 'X-MSS-API-USERKEY: YOUR_USER_KEY' \
  -H 'X-MSS-CUSTOM-DATE: Mon, 06 Apr 2026 00:22:19 GMT' \
  -H 'X-MSS-SIGNATURE: BASE64_SIGNATURE' \
  -d 'Url=https%3A%2F%2Fapp.example.com%2Fwebhooks%2Fportal-v2' \
  -d 'Enabled=true' \
  -d 'Events=ProposalStatusChanged%2CProposalBuildStatusChanged%2CProposalOutlineStatusChanged'

{
  "subscriptionId": 42,
  "url": "https://app.example.com/webhooks/portal-v2",
  "description": "Production webhook",
  "enabled": true,
  "secretKey": "whsec_a1b2c3d4e5f6...",
  "events": [
    "ProposalStatusChanged",
    "ProposalBuildStatusChanged",
    "ProposalOutlineStatusChanged"
  ]
}