Skip to main content
This guide explains how Nango receives and routes ConnectWise PSA webhooks.

​
How it works

  1. ConnectWise sends a signed POST request to your Nango webhook URL when a subscribed event occurs.
  2. Nango verifies the signature using the signing key referenced in the payload’s Metadata.key_url (trusted ConnectWise cloud subdomains are accepted by default; self-hosted origins require connection metadata).
  3. Nango routes the webhook to the matching connection(s), then either forwards it to your app or runs a sync (onWebhook).

​
Connection routing

ConnectWise webhook payloads include a ProductInstanceId field identifying the tenant the event belongs to. Nango routes each webhook to the connection(s) whose metadata.productInstanceId exactly matches the payload’s ProductInstanceId.
You must set metadata.productInstanceId on each connection for webhook routing to work. If it is unset (or does not match the ProductInstanceId in the payload), the connection receives no webhooks. The match is case-sensitive.

​
Set metadata.productInstanceId on a connection

Set metadata.productInstanceId to the ConnectWise Product Instance ID for that tenant — the same Product Instance ID used in the connection’s credentials (the value ConnectWise sends as ProductInstanceId in the webhook payload). Set it via the API:
PATCH merges the key into existing metadata; use POST if you want to replace all metadata. You can also set it from a post-connection-creation event function with nango.updateMetadata({ productInstanceId }) once you have the Product Instance ID for the connection. For a self-hosted instance, also set metadata.connectwiseWebhookKeyOrigin to the exact HTTPS origin that serves its callback signing keys:
Set this value from trusted backend configuration, not an incoming webhook. Use an HTTPS origin with no path, query, fragment, or credentials. The host and port must match exactly. Cloud connections need no new setting. Custom-origin events reach only connections with a matching Product Instance ID and configured origin, after signature verification. All signing-key requests, including cloud requests, block redirects and private network addresses and validate DNS results at connection time. They use a direct HTTPS connection, a 10-second timeout, and a 64 KiB response limit. Deployments that require an outbound proxy or a redirecting key endpoint need a compatible direct endpoint before using this handler.

​
Handle the webhook

Once routed to a connection, you have two options:
  • Forward it to your app — Nango verifies the signature and forwards the event to your webhook URL with connection attribution. See External webhook forwarding.
  • Process it in a sync — run a sync when the webhook arrives using webhookSubscriptions and onWebhook in a sync script. See Real-time syncs.
Need help getting started? Get help in the community.