Create a Webhook Subscription

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=proposal.status_changed' \
  -d 'Events=proposal.build.status_update' \
  -d 'Description=Production+webhook'

import requests
from portal_auth import sign_request

url = "https://api.portal.io/public/webhook/subscribe"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
content_type = "application/x-www-form-urlencoded"
signature = sign_request("POST", url, content_type, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.post(url, headers={
    "Accept": "application/json",
    "Content-Type": content_type,
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
}, data=[
    ("Url", "https://app.example.com/webhooks/portal"),
    ("Events", "proposal.status_changed"),
    ("Events", "proposal.build.status_update"),
    ("Description", "Production webhook"),
])
print(response.json())

const { signRequest } = require('./portalAuth');

const url = "https://api.portal.io/public/webhook/subscribe";
const timestamp = new Date().toUTCString();
const contentType = "application/x-www-form-urlencoded";
const signature = signRequest("POST", url, contentType, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": contentType,
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    },
    body: new URLSearchParams([
        ["Url", "https://app.example.com/webhooks/portal"],
        ["Events", "proposal.status_changed"],
        ["Events", "proposal.build.status_update"],
        ["Description", "Production webhook"],
    ])
});
const data = await response.json();
console.log(data);

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

POST

public

webhook

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=proposal.status_changed' \
  -d 'Events=proposal.build.status_update' \
  -d 'Description=Production+webhook'

import requests
from portal_auth import sign_request

url = "https://api.portal.io/public/webhook/subscribe"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
content_type = "application/x-www-form-urlencoded"
signature = sign_request("POST", url, content_type, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.post(url, headers={
    "Accept": "application/json",
    "Content-Type": content_type,
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
}, data=[
    ("Url", "https://app.example.com/webhooks/portal"),
    ("Events", "proposal.status_changed"),
    ("Events", "proposal.build.status_update"),
    ("Description", "Production webhook"),
])
print(response.json())

const { signRequest } = require('./portalAuth');

const url = "https://api.portal.io/public/webhook/subscribe";
const timestamp = new Date().toUTCString();
const contentType = "application/x-www-form-urlencoded";
const signature = signRequest("POST", url, contentType, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": contentType,
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    },
    body: new URLSearchParams([
        ["Url", "https://app.example.com/webhooks/portal"],
        ["Events", "proposal.status_changed"],
        ["Events", "proposal.build.status_update"],
        ["Description", "Production webhook"],
    ])
});
const data = await response.json();
console.log(data);

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

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.

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=proposal.status_changed' \
  -d 'Events=proposal.build.status_update' \
  -d 'Description=Production+webhook'

import requests
from portal_auth import sign_request

url = "https://api.portal.io/public/webhook/subscribe"
timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
content_type = "application/x-www-form-urlencoded"
signature = sign_request("POST", url, content_type, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

response = requests.post(url, headers={
    "Accept": "application/json",
    "Content-Type": content_type,
    "X-MSS-API-APPID": "YOUR_APP_ID",
    "X-MSS-API-USERKEY": "YOUR_USER_KEY",
    "X-MSS-CUSTOM-DATE": timestamp,
    "X-MSS-SIGNATURE": signature
}, data=[
    ("Url", "https://app.example.com/webhooks/portal"),
    ("Events", "proposal.status_changed"),
    ("Events", "proposal.build.status_update"),
    ("Description", "Production webhook"),
])
print(response.json())

const { signRequest } = require('./portalAuth');

const url = "https://api.portal.io/public/webhook/subscribe";
const timestamp = new Date().toUTCString();
const contentType = "application/x-www-form-urlencoded";
const signature = signRequest("POST", url, contentType, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

const response = await fetch(url, {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": contentType,
        "X-MSS-API-APPID": "YOUR_APP_ID",
        "X-MSS-API-USERKEY": "YOUR_USER_KEY",
        "X-MSS-CUSTOM-DATE": timestamp,
        "X-MSS-SIGNATURE": signature
    },
    body: new URLSearchParams([
        ["Url", "https://app.example.com/webhooks/portal"],
        ["Events", "proposal.status_changed"],
        ["Events", "proposal.build.status_update"],
        ["Description", "Production webhook"],
    ])
});
const data = await response.json();
console.log(data);

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

Authorizations

X-MSS-API-APPID

string

header

required

Portal application identifier used as part of HMAC-authenticated API requests.

X-MSS-API-USERKEY

string

header

required

Portal user API key used together with the HMAC signature headers.

X-MSS-CUSTOM-DATE

string

header

required

Timestamp header included in the signed request to prevent replay attacks.

X-MSS-SIGNATURE

string

header

required

HMAC-SHA256 signature for the request, calculated over the canonical string defined in the authentication docs.

Headers

enum<string>

required

Accept Header

Available options:

application/json

Body

application/json

Webhook Services

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

One or more event-type names to subscribe to. Duplicate names are ignored case-insensitively. Returns 400 listing any unrecognised event names. Currently supported webhook event names are implementation-defined; see the published webhook documentation for the current set.

description

string

Optional human-readable label for this subscription. Trimmed before storage; whitespace-only values are stored as null.

Response

Success

Webhook subscription returned by the public webhook management API

subscriptionId

integer<int64>

required

Unique numeric identifier of the webhook subscription

url

string

required

HTTPS URL that receives webhook POST deliveries

enabled

boolean

required

Whether the subscription is enabled

events

string[]

required

Event names that trigger this subscription

description

string

Optional human-readable label for the subscription

secretKey

string

Signing secret used to verify webhook deliveries. Returned on create and update responses only; omitted from list responses.

⌘I

Authentication

Proposals

Proposal Items

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Create a Webhook Subscription

Authorizations

Headers

Body

Response