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

Headers

enum<string>

required

Accept Header

Available options:

application/json

X-MSS-API-APPID

string

required

Application Id

X-MSS-CUSTOM-DATE

string

required

A date timestamp of the request

X-MSS-SIGNATURE

string

required

A signature for the request

X-MSS-API-USERKEY

string

required

User API Key

Body

application/x-www-form-urlencoded

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. Only returned when a new secret is issued, such as during create or update operations

List Users in Your Account

List Your Webhook Subscriptions

⌘I

Authentication

Proposals

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Create a Webhook Subscription

Headers

Body

Response