Skip to main content
Registers a new webhook subscription for your dealer account. Provide an HTTPS callback URL and the list of event types you want to receive. Portal.io will POST a signed JSON payload to your URL whenever a subscribed event occurs. The response includes a secretKey — store this securely, as it is used to verify the authenticity of every webhook delivery sent to your endpoint.
The secretKey is only returned once at creation time. If you lose it, you will need to update the subscription to generate a new one.

​
Request

POST /public/webhook/subscribe

​
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.

​
Body Parameters

​
Url
string
required
Absolute HTTPS URL that will receive webhook POST payloads. Must use the https:// scheme and resolve to a publicly routable host. Private, loopback, and link-local addresses are rejected. The value is trimmed before storage.
​
Events
string
required
Comma-separated list of event type strings to subscribe to (e.g. ProposalStatusChanged,ProposalBuildStatusChanged). See the Webhook Events reference for all available event types.
​
Description
string
Optional human-readable label for this subscription. Useful when managing multiple subscriptions.

​
Response

​
200 Success

​
subscriptionId
integer
required
Unique numeric identifier of the newly created webhook subscription. Use this ID in update and delete requests.
​
url
string
required
The HTTPS callback URL that will receive event payloads.
​
description
string
The description label, if provided.
​
enabled
boolean
required
Whether the subscription is currently active. Newly created subscriptions are enabled by default.
​
secretKey
string
required
HMAC secret used to sign webhook deliveries. Store this value securely. Verify incoming requests by computing HMAC_SHA256(secretKey, timestamp + "." + requestBody) and comparing to the v1 value in the X-Webhook-Signature header.
​
events
array
required
Array of event type strings this subscription is registered for.

​
Error Codes

CodeMeaning
400Validation failed. Common causes: URL is not HTTPS or resolves to a private address, unrecognized event names.
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/subscribe' \
  -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' \
  -d 'Events=ProposalStatusChanged%2CProposalBuildStatusChanged' \
  -d 'Description=Production+webhook'

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