> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to map an app-level webhook to the right Connected Users

> Set Provider ID so one app-level Custom Webhook runs only for the users it belongs to, instead of everyone with a blank providerId.

Breadcrumb

This guide shows you how to use **Provider ID** so one [app-level Custom Webhook](https://docs.useparagon.com/resources/custom-webhooks.md) 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](#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](https://docs.useparagon.com/resources/custom-webhooks.md) 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](https://docs.useparagon.com/resources/custom-webhooks.md)).

| Provider ID on the trigger | Who runs (among users who have the workflow enabled) |
| - | - |
| A unique value from User Profile / `providerData` | Only users whose stored Provider ID equals the ID in the event |
| Empty / blank | Every user whose `providerId` is also empty |

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](https://docs.useparagon.com/resources/custom-integrations.md), [getUser](https://docs.useparagon.com/apis/api-reference.md#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](https://docs.useparagon.com/resources/custom-webhooks.md). 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

| What you see | Cause | Fix |
| - | - | - |
| One webhook, N executions, one per Connected User | Provider ID is blank and those users have empty `providerId` | Set User Profile, set Provider ID to `{{profileData...}}`, reconnect users |
| No executions | The event field does not equal any user's Provider ID, or the workflow is not enabled | Compare the payload ID to `/sdk/me` `providerId` / `providerData` |
| Test Connect Portal user has no `providerData` in the variable menu | The test user connected before User Profile was saved, or the profile request never ran | Reconnect that test user after User Profile is configured |
| Users connected before Step 4 still have `providerId: ""` | User Profile is not retroactive | Disconnect and reconnect those users |
| Disconnect/reconnect wipes Connect Portal settings | Expected for a full reconnect | Plan to restore User Settings after reconnect |

## 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)

## Related articles

* [Custom Webhooks](https://docs.useparagon.com/resources/custom-webhooks.md)
* [Custom Integrations](https://docs.useparagon.com/resources/custom-integrations.md)
* [API Resource Trigger](https://docs.useparagon.com/workflows/triggers/api-resource-trigger.md)
* [getUser](https://docs.useparagon.com/apis/api-reference.md#getuser)