Adding info re: emitting to workflows (#15442)

Author: dannyroosevelt

docs-v2/pages/connect/api.mdx

@@ -205,8 +205,9 @@ curl -X POST https://api.pipedream.com/v1/connect/rate_limits \
 
 **Example usage**
 
-```
-# The response will include a rate limit token. Pass it as a header in your downstream requests to the Connect API.
+```bash
+# The response will include a rate limit token. 
+# Pass it as a header in your downstream requests to the Connect API.
 # Below is an example request that runs the "List Commits" action for the Gitlab app.
 
 curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run" \
@@ -2009,7 +2010,7 @@ curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run
 
 #### Deploy a trigger
 
-Deploy a trigger component for a Pipedream Connect user in a project.
+Deploy a trigger component that will emit events to a webhook or workflow for a Pipedream Connect user.
 
 ```text
 POST /triggers/deploy
@@ -2039,12 +2040,22 @@ which you want to execute the action.
 
 ---
 
-`webhook_url` **string**
+`webhook_url` **string** (_optional_)
 
 The URL to which the trigger will send events.
 
 ---
 
+`workflow_url` **string** (_optional_)
+
+The Pipedream workflow ID to which you want to emit events (ex, `p_1234567`).
+
+<Callout type="warning">
+The workflow must be in the same Pipedream project as the trigger.
+</Callout>
+
+---
+
 `dynamic_props_id` **string** (_optional_)
 
 The ID of the last prop reconfiguration (if applicable).

docs-v2/pages/connect/workflows.mdx

@@ -38,14 +38,16 @@ Read [the quickstart](/quickstart/) to learn more.
 
 [Create a new workflow](/workflows#how-do-i-create-a-new-workflow) or open an existing one.
 
-### Add an HTTP trigger, configure OAuth
+### Add an HTTP trigger
 
-1. Add an [HTTP trigger](/workflows/triggers#http) to your workflow.
-2. [Configure **OAuth** authorization](/workflows/triggers#oauth) on the trigger.
+To get started building workflows for your end users:
 
-<Callout type="info">
-To securely run workflows for end users, **configuring OAuth authorization on the trigger is optional but strongly recommended.** [Create a Pipedream OAuth client](/rest-api/auth#creating-an-oauth-client) to authenticate requests to the Pipedream API and workflows.
-</Callout>
+1. Add an [HTTP trigger](/workflows/triggers#http) to your workflow
+2. Generate a test event with the required headers:
+   - `x-pd-environment: development`
+   - `x-pd-external-user-id: {your_external_user_id}`
+
+See the [Triggering your workflow](#triggering-your-workflow) section below for details on securing your workflow with OAuth and deploying triggers on behalf of your end users.
 
 ### Configure accounts to use your end users' auth
 
@@ -235,7 +237,7 @@ curl -X POST https://{your-endpoint-url} \
 We plan to improve this interface in the future, and potentially allow developers to store end user metadata and configuration data alongside the connected account for your end users, so you won't need to pass the data at runtime. [Let us know](https://pipedream.com/support) if that's a feature you'd like to see.
 </Callout>
 
-## Testing workflow steps
+## Testing
 
 To test a step using the connected account of one of your end users in the builder, you'll need a few things to be configured so that your workflow knows which account to use.
 
@@ -252,6 +254,114 @@ To test a step using the connected account of one of your end users in the build
 
 <Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1733533298/pd-connect-headers_c1x7an.png" alt="Include required headers" width={600} height={529} />
 
+## Triggering your workflow
+
+You have two options for triggering workflows that run on behalf of your end users:
+
+1. [Invoke via HTTP webhook](#http-webhook)
+2. [Deploy an event source](#deploy-an-event-source) (Slack, Gmail, etc.)
+
+### HTTP Webhook
+
+The most common way to trigger workflows is via HTTP webhook. We strongly recommend [creating a Pipedream OAuth client](/rest-api/auth#creating-an-oauth-client) and authenticating inbound requests to your workflows.
+
+To get started, you'll need:
+
+- [OAuth client ID and secret](/rest-api/auth#creating-an-oauth-client) (optional but recommended)
+- Your [project ID](/projects#finding-your-projects-id)
+- Your workflow's HTTP endpoint URL
+- The [external user ID](/connect/api#external-users) of your end user
+- The [Connect environment](/connect/environments) 
+
+<Tabs items={['TypeScript', 'Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```typescript
+import { createBackendClient, HTTPAuthType } from "@pipedream/sdk/server";
+ 
+// These secrets should be saved securely and passed to your environment
+const pd = createBackendClient({
+  environment: "development", // change to production if running for a test production account, or in production
+  credentials: {
+    clientId: "{oauth_client_id}",
+    clientSecret: "{oauth_client_secret}",
+  },
+  projectId: "{your_project_id}"
+});
+
+await pd.invokeWorkflowForExternalUser(
+  "{your_endpoint_url}", // pass the endpoint ID or full URL here
+  "{your_external_user_id}" // The end user's ID in your system
+  {
+    method: "POST",
+    body: {
+      message: "Hello World"
+    }
+  },
+  HTTPAuthType.OAuth // Will automatically send the Authorization header with a fresh token
+)
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```javascript
+import { createBackendClient } from "@pipedream/sdk/server";
+
+// These secrets should be saved securely and passed to your environment
+const client = createBackendClient({
+  environment: "development", // change to production if running for a test production account, or in production
+  credentials: {
+    clientId: "{oauth_client_id}", 
+    clientSecret: "{oauth_client_secret}"
+  },
+  projectId: "{your_project_id}"
+});
+
+const response = await client.invokeWorkflowForExternalUser(
+  "{your_endpoint_url}", // pass the endpoint ID or full URL here
+  "{your_external_user_id}" // The end user's ID in your system
+  {
+    method: "POST",
+    body: {
+      message: "Hello World"
+    }
+  }
+)
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+# First, obtain an OAuth access token
+curl -X POST https://api.pipedream.com/v1/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "grant_type": "client_credentials",
+    "client_id": "{oauth_client_id}",
+    "client_secret": "{oauth_client_secret}"
+  }'
+
+# The response will include an access_token. Use it in the Authorization header below.
+
+curl -X POST https://{your-endpoint-url} \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer {access_token}" \
+  -H 'X-PD-External-User-ID: {your_external_user_id}' \
+  -H 'X-PD-Environment: development' \  # 'development' or 'production'
+  -d '{
+    "message": "Hello, world"
+  }'
+```
+</Tabs.Tab>
+</Tabs>
+
+### Deploy an event source
+
+You can [programmatically deploy triggers via the API](/connect/api#deploy-a-trigger) to have events from integrated apps (like [new Slack messages](/apps/slack/triggers/new-message-in-channels) or [new emails in Gmail](/apps/gmail/triggers/new-email-received)) trigger your workflow. This allows you to:
+
+- Deploy triggers for specific users from your application
+- Configure trigger parameters per-user
+- Manage deployed triggers via the API
+
+See the [API documentation](/connect/api#deploy-a-trigger) for detailed examples of deploying and managing triggers.
+
 ## Troubleshooting
 
 For help debugging issues with your workflow, you can return verbose error messages to the caller by configuring the HTTP trigger to **Return a custom response from your workflow**.