How to send an App Event to a single configuration

This guide shows you how to send an App Event so it runs for one Multi-Configuration instance, not every configuration that has the workflow enabled. If you are already seeing duplicate Task History rows from one event, start with Workflow runs twice from one App Event or integration trigger.

Prerequisites

Multi-Configuration is enabled for the integration.
The Connected User has at least one connected account (credential) and at least one configuration.
You can mint a Paragon User Token for that user (installing the Connect SDK).

Why the App Events example runs more than once

The App Events request is untargeted. Paragon accepts the event (201) and starts every matching workflow for that user, including every configuration that has the workflow enabled. That is the right default when each configuration should handle the event with its own settings. It is the wrong default when you meant “create this record in one project / one folder / one team.” To pin the event to one configuration, send the credential UUID and the configuration ID on the request.

Step 1: Read the credential and configuration IDs

Call paragon.getUser() or:

GET https://api.useparagon.com/projects/<Project ID>/sdk/me
Authorization: Bearer <Paragon User Token>

Under integrations.<integration> you get:

allCredentials: connected accounts. Each has an id (the credential UUID) and a configurations array.
allConfigurations: the configurations for that integration.

Each configuration includes:

id: Paragon’s configuration UUID. You can send this as X-Paragon-Configuration-Id as-is.
externalId: the ID you passed to createConfiguration, if any. Send it as ext: plus that value, for example ext:141.
A credential UUID for the parent connected account (the same value as the parent credential’s id). Send that as X-Paragon-Credential.

The configuration UUID is stable for the life of that configuration. The credential UUID is stable for the life of the connected account; it changes if the user disconnects and reconnects. If you store IDs in your database, refresh them from /sdk/me after a disconnect/reconnect so you do not keep a stale credential UUID.

Step 2: Send the App Event with both headers

POST https://api.useparagon.com/projects/<Project ID>/sdk/events/trigger
Authorization: Bearer <Paragon User Token>
Content-Type: application/json
X-Paragon-Credential: <credential UUID>
X-Paragon-Configuration-Id: <configuration UUID or ext:your-external-id>

{
  "name": "Contact Created",
  "payload": {
    "name": "Brandon",
    "email": "[email protected]"
  }
}

X-Paragon-Configuration-Id accepts a configuration UUID, or an external ID with the ext: prefix. Do not send the bare external ID. Send both headers. Sending only X-Paragon-Configuration-Id can return 400 Bad Request. The same request without either header returns 201 and fans out. The SDK equivalent is selectedConfigurationId on paragon.event. See Calling the API. For a request that must name both a credential and a configuration, use the REST call above.

Verify it worked

The App Event endpoint responds 201.
Task History shows one execution of the workflow for that user, for the configuration you targeted, even if other configurations still have the workflow enabled.

Common issues

What you see	Cause	Fix
Two or more executions, identical payloads, no error	The event was untargeted and more than one configuration has the workflow enabled	Add both headers. See Workflow runs twice from one App Event or integration trigger.
`400 Bad Request` after adding `X-Paragon-Configuration-Id`	Missing `X-Paragon-Credential`, or a configuration ID that is not a UUID and not `ext:`-prefixed	Send both headers. Use a configuration UUID or `ext:` plus your external ID.
`201` but still N executions	The configuration ID did not match, or you targeted a configuration that is not the only one you intended	Confirm the IDs against `/sdk/me`. Remember `ext:` on external IDs.
Stale credential UUID after reconnect	The user disconnected and connected again; Paragon issued a new credential UUID	Read `/sdk/me` again and update what you store.

Still stuck?

Send support the request URL (not an on-prem custom hostname unless you are on-prem), the two header names and whether each was present, the exact X-Paragon-Configuration-Id value (UUID vs ext: vs bare external ID), the HTTP status, and the Task History IDs.

​Prerequisites

​Why the App Events example runs more than once

​Step 1: Read the credential and configuration IDs

​Step 2: Send the App Event with both headers

​Verify it worked

​Common issues

​Still stuck?

​Related articles