Beta

Webhook Connector: receive public events into a private service

Purpose, safe use cases and step-by-step setup for forwarding provider webhooks to one fixed private upstream.

Steps

Follow these in order.

01Understand the boundaryA public provider calls BusinessProxy; the connector dials out from your network to one fixed private URL.
02Choose a safe use casePayment notifications, source-control events and partner system callbacks are good fits when the private target is fixed.
03Sign in to the management CLIUse browser/device approval; do not paste user access tokens into operator notes.
04Create the connector and runtime secretCreate a webhook connector, copy the one-time runtime token and store it as a secret.
05Create the endpointBind the public URL to one private upstream, method list, body limit, timeout and rate limit.
06Run, test and monitorLoad runtime env, run checks, start the process and send a sanitized smoke request.
07Rotate or revokeRotate connector tokens and endpoint secrets separately; revoke or disable when delivery must stop.

Reference

Implementation details for setup and review.

What the Webhook Connector is forWebhook Connector lets an external service deliver an HTTP event to a private internal service without opening an inbound port to that private network. The public request lands on a BusinessProxy URL with a high-entropy secret, then BusinessProxy queues the delivery for the selected connector. The connector polls or streams outbound to BusinessProxy and forwards the request only to the fixed private upstream configured for that endpoint.

The caller cannot choose the private upstream URL.
The connector token is separate from App Gateway connector tokens.
Request and response bodies are not written to logs by the connector.

Safe use casesUse this connector when one known external service needs to notify one private handler and the private handler will still verify the event using provider-specific proof. Do not use it as a public proxy to arbitrary internal URLs.

Payments: a provider posts an event to BusinessProxy, then a private billing service confirms payment id, amount and currency through the provider API.
Source control: a repository service notifies a private build controller about a new tag or merge request.
Partner systems: a customer or supplier system sends an order-state event to one private integration handler.
Internal tools: a form service posts a signed event to a private helpdesk or CRM intake service.

Before you startPrepare a workspace, a private handler URL reachable from the connector host, and an operator account that can approve webhook connector management access in the BusinessProxy dashboard.

Use HTTPS for the BusinessProxy API in normal environments.
Store runtime tokens and endpoint secrets in a secret store, not in tickets or screenshots.
For payment events, never trust the event body alone; confirm the payment through the provider before granting value.

Sign in to managementThe management command opens a browser approval page and stores a scoped management credential locally. For automation, a separately issued user access token can be supplied through BUSINESSPROXY_ACCESS_TOKEN, but browser approval is the normal operator path.

export BUSINESSPROXY_API_URL=https://api.business-proxy.com

webhook-connector auth login --api-url "$BUSINESSPROXY_API_URL"
webhook-connector auth status

Create the connector and runtime envCreate one webhook connector for the private network that will receive deliveries. The create response prints a one-time runtime token. Save it immediately and generate an env file for the host that will run the connector.

webhook-connector connector create \
  --workspace-id <workspace-id> \
  --name "payment notifications" \
  --json

webhook-connector config env-template \
  --workspace-id <workspace-id> \
  --connector-id <webhook-connector-id> \
  --token <one-time-runtime-token> \
  > .env.webhook-connector

Create the receiving endpointThe endpoint binds one public BusinessProxy URL to one fixed private upstream. Start with POST only, set a body limit, timeout and rate limit, then give the returned callback URL to the external provider.

webhook-connector endpoint create \
  --workspace-id <workspace-id> \
  --connector-id <webhook-connector-id> \
  --name "payment hook" \
  --provider custom \
  --auth-mode header \
  --token-header-name X-Webhook-Token \
  --upstream http://10.0.0.10:13000/payment/provider/notification \
  --method POST \
  --max-body 1048576 \
  --timeout 30 \
  --rate-limit 60 \
  --json

Run and testLoad the generated env file on the connector host, run local checks, then start the process. After the process is online, send a smoke request to the public URL. The smoke output redacts the URL secret.

set -a
. ./.env.webhook-connector
set +a

webhook-connector config check
webhook-connector doctor
webhook-connector run

webhook-connector smoke \
  --callback-url "https://wh-example.business-proxy.com/custom/<endpoint-secret>" \
  --secret <endpoint-secret> \
  --body '{}'

Rotate, revoke or disableRotate the connector runtime token when it may be exposed or as part of regular maintenance. Rotate the endpoint secret when the public URL must change at the provider. Revoke the endpoint secret to stop the current URL without issuing a replacement, or disable the endpoint to stop delivery completely.

webhook-connector connector rotate-token \
  --workspace-id <workspace-id> \
  --connector-id <webhook-connector-id>

webhook-connector endpoint rotate-secret \
  --workspace-id <workspace-id> \
  --endpoint-id <webhook-endpoint-id>

webhook-connector endpoint revoke-secret \
  --workspace-id <workspace-id> \
  --endpoint-id <webhook-endpoint-id>

webhook-connector endpoint disable \
  --workspace-id <workspace-id> \
  --endpoint-id <webhook-endpoint-id>

TroubleshootingMost failures are caused by a wrong API URL, expired management credential, rotated runtime token, unreachable private upstream, TLS trust issue, method/body/rate limit, or an SSRF guard blocking an unsafe target.

API HTTPS error: use HTTPS, or for loopback development only set BUSINESSPROXY_DEVELOPMENT_ALLOW_HTTP_API=true for management commands and WEBHOOK_CONNECTOR_DEVELOPMENT_ALLOW_HTTP_API=true for runtime.
Management auth error: run auth status, then auth logout and auth login if the stored credential is expired or belongs to another workspace.
Runtime unauthorized: refresh WEBHOOK_CONNECTOR_TOKEN after token rotation and restart the connector.
Upstream timeout: verify that the connector host can reach the private URL by DNS, TCP and TLS.
SSRF guard block: keep the endpoint bound to the intended fixed target; do not pass target URLs from incoming requests.