Skip to main content
This guide shows you how to use Provider ID so one app-level Custom Webhook runs only for the Connected Users it belongs to. If you leave Provider ID blank, one inbound event can start a workflow for every user whose providerId is empty. If you are already seeing one webhook create dozens of executions, jump to Why a blank Provider ID runs for everyone.

​
Prerequisites

  • A Custom Webhook (or API Resource Trigger) whose type is App-level. Custom Webhooks require a Pro plan or above.
  • For a custom integration: you can edit Step 4. API Setup and the User Profile section.
  • The inbound event includes a stable ID you can match (user id, account id, tenant id).

​
Why a blank Provider ID runs for everyone

App-level webhooks are registered once. Paragon then decides which Connected Users should run by matching a field on the event to each user’s Provider ID (Event Routing). Blank matching is the wrong default if you switched to app-level to register one URL. You get one URL, and also one execution per matching user, every time the provider fires. That fan-out has three costs:
  • Wrong-account work. If routing inside the workflow is wrong, steps run in the wrong user’s connection.
  • Task History noise. Five events and twenty blank-providerId users is 100 executions. Finding the one that failed is slow.
  • Queue. The same math fills the execution queue. At small N it is fine. It does not stay small.
Do not leave Provider ID blank to “match everyone and filter later” unless you have accepted those costs. Set User Profile so each connection has a real Provider ID.

​
Step 1: Save a unique ID on User Profile

In the Custom Integration wizard, open Step 4. API Setup. At the bottom of the left sidebar, open User Profile. Configure an API Request (typical: a users/me style endpoint) or a JWT Decode so Paragon stores identifying fields on the connection. Those fields are available later as providerData on the user (Custom Integrations, getUser). Use a value that also appears on inbound webhook events. If the provider has no profile endpoint, you need some other unique field you control at connect time. Do not rely on an empty providerId. Existing connections do not pick this up automatically. Users who connected before you saved User Profile must disconnect and reconnect. They will need to fill in Connect Portal settings again.

​
Step 2: Match the event field to Provider ID

In the Custom Webhook wizard, Step 3. Event Routing:
  1. Point the event-side ID at the payload (or header) field that identifies the tenant.
  2. Set Provider ID to the User Profile path, for example {{profileData.user.user_id}}. Use the path that matches your providerData shape.
Paragon runs the workflow for each Connected User whose stored Provider ID equals that event field, and who has the workflow enabled. Comparison is not strict about number vs string: 134450 matches "134450". Prefer storing and sending the same type anyway.

​
Step 3: Register one webhook URL

Keep the trigger App-level. Register the Webhook Target URL once in the provider’s app settings, as in Custom Webhooks, Manual Setup. You should not register a per-user URL for this trigger.

​
Verify it worked

  1. Connect at least two test users with different User Profile IDs, and enable the workflow on both.
  2. Send an event whose ID matches only user A.
  3. Task History should show executions for A (and any other user who shares that Provider ID), not for B.
  4. Confirm providerId is non-empty on paragon.getUser() / GET /sdk/me for those connections.

​
Common issues

​
Still having issues?

Send support:
  • Whether the trigger is App-level or User-level
  • The Event Routing fields (event ID path and Provider ID / profileConfigKey path), and whether Provider ID is blank
  • How many Connected Users have this workflow enabled, and how many of them have empty providerId
  • One Task History ID from a fan-out burst, and how many executions that single inbound event produced
  • A redacted /sdk/me snippet showing providerId and providerData (no tokens)