Skip to content

Commit 7d1bbdc

Browse files
dannyrooseveltdannyroosevelt
authored
Native triggers docs (#16310)
1 parent 7ddb081 commit 7d1bbdc

File tree

2 files changed

+210
-28
lines changed

2 files changed

+210
-28
lines changed

‎docs-v2/pages/connect/api.mdx‎

Lines changed: 32 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2011,6 +2011,10 @@ curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run
20112011

20122012
#### Deploy a trigger
20132013

2014+
<Callout type="info">
2015+
See [here](/connect/components/#deploying-triggers) for more info on supported trigger types with example payloads
2016+
</Callout>
2017+
20142018
Deploy a trigger component that will emit events to a webhook or workflow for a Pipedream Connect user.
20152019

20162020
```text
@@ -2492,14 +2496,14 @@ curl -X GET \
24922496
Retrieve a single deployed trigger for a given user.
24932497

24942498
```text
2495-
GET /deployed-triggers/{deployed_component_id}/
2499+
GET /deployed-triggers/{deployed_trigger_id}/
24962500
```
24972501

24982502
##### Path parameters
24992503

2500-
`dcid` **string**
2504+
`deployed_trigger_id` **string**
25012505

2502-
The deployed component ID for the trigger you'd like to retrieve.
2506+
The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`).
25032507

25042508
##### Query parameters
25052509

@@ -2590,7 +2594,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
25902594

25912595
curl -X GET \
25922596
-G \
2593-
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/" \
2597+
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/" \
25942598
-H "Authorization: Bearer {access_token}" \
25952599
-H "Content-Type: application/json" \
25962600
-H "x-pd-environment: development" \
@@ -2677,14 +2681,14 @@ curl -X GET \
26772681
Delete deployed trigger for a given user.
26782682

26792683
```text
2680-
DELETE /deployed-triggers/{deployed_component_id}/
2684+
DELETE /deployed-triggers/{deployed_trigger_id}/
26812685
```
26822686

26832687
##### Path parameters
26842688

2685-
`dcid` **string**
2689+
`deployed_trigger_id` **string**
26862690

2687-
The deployed component ID for the trigger you'd like to retrieve.
2691+
The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`).
26882692

26892693
##### Query parameters
26902694

@@ -2768,7 +2772,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
27682772

27692773
curl -X DELETE \
27702774
-G \
2771-
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/" \
2775+
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/" \
27722776
-H "Authorization: Bearer {access_token}" \
27732777
-H "Content-Type: application/json" \
27742778
-H "x-pd-environment: development" \
@@ -2787,14 +2791,14 @@ Pipedream returns a `204 No Content` response on successful deletion
27872791
Retrieve a list of the last events that a deployed trigger emitted.
27882792

27892793
```text
2790-
GET /deployed-triggers/{deployed_component_id}/events/
2794+
GET /deployed-triggers/{deployed_trigger_id}/events/
27912795
```
27922796

27932797
##### Path parameters
27942798

2795-
`dcid` **string**
2799+
`deployed_trigger_id` **string**
27962800

2797-
The deployed component ID for the trigger you'd like to retrieve.
2801+
The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`).
27982802

27992803
##### Query parameters
28002804

@@ -2889,7 +2893,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
28892893

28902894
curl -X GET \
28912895
-G \
2892-
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/events" \
2896+
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/events" \
28932897
-H "Authorization: Bearer {access_token}" \
28942898
-H "Content-Type: application/json" \
28952899
-H "x-pd-environment: development" \
@@ -2984,14 +2988,14 @@ curl -X GET \
29842988
Retrieve the list of webhook URLs listening to a deployed trigger.
29852989

29862990
```text
2987-
GET /deployed-triggers/{deployed_component_id}/webhooks/
2991+
GET /deployed-triggers/{deployed_trigger_id}/webhooks/
29882992
```
29892993

29902994
##### Path parameters
29912995

2992-
`dcid` **string**
2996+
`deployed_trigger_id` **string**
29932997

2994-
The deployed component ID for the trigger you'd like to retrieve.
2998+
The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`).
29952999

29963000
##### Query parameters
29973001

@@ -3081,7 +3085,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
30813085

30823086
curl -X GET \
30833087
-G \
3084-
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \
3088+
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/webhooks/" \
30853089
-H "Authorization: Bearer {access_token}" \
30863090
-H "Content-Type: application/json" \
30873091
-H "x-pd-environment: development" \
@@ -3105,14 +3109,14 @@ curl -X GET \
31053109
Update the list of webhook URLs that will listen to a deployed trigger.
31063110

31073111
```text
3108-
PUT /deployed-triggers/{deployed_component_id}/webhooks/
3112+
PUT /deployed-triggers/{deployed_trigger_id}/webhooks/
31093113
```
31103114

31113115
##### Path parameters
31123116

3113-
`dcid` **string**
3117+
`deployed_trigger_id` **string**
31143118

3115-
The deployed component ID for the trigger you'd like to retrieve.
3119+
The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`).
31163120

31173121
##### Query parameters
31183122

@@ -3220,7 +3224,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
32203224
# This request will update the list of webhook URLs listening to the specified deployed trigger.
32213225

32223226
curl -X PUT \
3223-
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \
3227+
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/webhooks/" \
32243228
-H "Authorization: Bearer {access_token}" \
32253229
-H "Content-Type: application/json" \
32263230
-H "x-pd-environment: development" \
@@ -3244,14 +3248,14 @@ curl -X PUT \
32443248
Retrieve the list of workflow IDs listening to a deployed trigger.
32453249

32463250
```text
3247-
GET /deployed-triggers/{deployed_component_id}/workflows/
3251+
GET /deployed-triggers/{deployed_trigger_id}/workflows/
32483252
```
32493253

32503254
##### Path parameters
32513255

3252-
`dcid` **string**
3256+
`deployed_trigger_id` **string**
32533257

3254-
The deployed component ID for the trigger you'd like to retrieve.
3258+
The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`).
32553259

32563260
##### Query parameters
32573261

@@ -3341,7 +3345,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
33413345

33423346
curl -X GET \
33433347
-G \
3344-
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/workflows/" \
3348+
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/workflows/" \
33453349
-H "Authorization: Bearer {access_token}" \
33463350
-H "Content-Type: application/json" \
33473351
-H "x-pd-environment: development" \
@@ -3366,14 +3370,14 @@ curl -X GET \
33663370
Update the list of workflows that will listen to a deployed trigger.
33673371

33683372
```text
3369-
PUT /deployed-triggers/{deployed_component_id}/workflows/
3373+
PUT /deployed-triggers/{deployed_trigger_id}/workflows/
33703374
```
33713375

33723376
##### Path parameters
33733377

3374-
`dcid` **string**
3378+
`deployed_trigger_id` **string**
33753379

3376-
The deployed component ID for the trigger you'd like to retrieve.
3380+
The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`).
33773381

33783382
##### Query parameters
33793383

@@ -3482,7 +3486,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
34823486
# This request will update the list of webhook URLs listening to the specified deployed trigger.
34833487

34843488
curl -X PUT \
3485-
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \
3489+
"https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/webhooks/" \
34863490
-H "Authorization: Bearer {access_token}" \
34873491
-H "Content-Type: application/json" \
34883492
-H "x-pd-environment: development" \

‎docs-v2/pages/connect/components.mdx‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -812,3 +812,181 @@ retrieve, or update the source in the future.
812812
Refer to the [full Connect API reference](/connect/api#components) for questions and additional examples.
813813

814814
</Steps>
815+
816+
## Deploying triggers
817+
818+
These are 2 categories of triggers you can deploy on behalf of your end users:
819+
- [App-based event sources](#app-based-event-sources)
820+
- [Native triggers](#native-triggers)
821+
822+
<Callout type="info">
823+
Refer to the [full Connect API reference](/connect/api/#deploy-a-trigger) to list, retrieve, delete, and manage triggers for your user
824+
</Callout>
825+
826+
### App-based event sources
827+
- Listen for events that occur in other systems: for example, when [a new file is added to Google Drive](https://pipedream.com/apps/google-drive/triggers/new-files-instant) or when [a new contact is created in HubSpot](https://pipedream.com/apps/hubspot/triggers/new-or-updated-contact)
828+
- Deploying these triggers requires that your customers first connect their account using [Pipedream Connect Managed Auth](/managed-auth/quickstart), since the triggers are deployed on their behalf using account
829+
- Refer to the [quickstart above](#deploying-a-source) to get started
830+
831+
### Native triggers
832+
- You can also deploy native triggers, which don't require any authentication from your end users, so **you should skip the account connection process when configuring these triggers**
833+
- Because these triggers don't use a connected account from your end users, APIs to deploy and manage them are slightly different (see below)
834+
835+
#### HTTP Webhook
836+
Generate a unique HTTP webhook URL for your end users to configure in any other upstream service.
837+
838+
<Tabs items={['Node.js', 'HTTP (cURL)']}>
839+
<Tabs.Tab>
840+
```javascript
841+
const { data: deployedTrigger } = await pd.deployTrigger({
842+
externalUserId: "abc-123",
843+
id: "http-new-requests",
844+
webhookUrl: "https://events.example.com/http-new-requests"
845+
});
846+
847+
const {
848+
id: triggerId, // The unique ID of the deployed trigger
849+
endpoint_url: endpointUrl, // The endpoint URL to return to the user
850+
} = deployedTrigger;
851+
852+
// Parse and return the data you need
853+
```
854+
</Tabs.Tab>
855+
<Tabs.Tab>
856+
```bash
857+
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \
858+
-H "Content-Type: application/json" \
859+
-H "X-PD-Environment: {environment}" \
860+
-H "Authorization: Bearer {access_token}" \
861+
-d '{
862+
"external_user_id": "abc-123",
863+
"id": "http-new-requests",
864+
"webhook_url": "https://events.example.com/http-new-requests"
865+
}'
866+
867+
# Parse and return the data you need
868+
```
869+
</Tabs.Tab>
870+
</Tabs>
871+
872+
##### Example response
873+
874+
```json
875+
{
876+
"id": "hi_zbGHMx",
877+
"key": "xxxxxxxxxx",
878+
"endpoint_url": "http://xxxxxxxxxx.m.pipedream.net",
879+
"custom_response": true,
880+
"created_at": 1744508049,
881+
"updated_at": 1744508049
882+
}
883+
```
884+
885+
#### Schedule
886+
Deploy a timer to act as a cron job that will emit an event on a custom schedule you or your users define.
887+
888+
<Tabs items={['Node.js', 'HTTP (cURL)']}>
889+
<Tabs.Tab>
890+
```javascript
891+
const { data: deployedTrigger } = await pd.deployTrigger({
892+
externalUserId: "abc-123",
893+
id: "schedule-custom-interval",
894+
configuredProps: {
895+
"cron": {
896+
"intervalSeconds": 900
897+
}
898+
},
899+
webhookUrl: "https://events.example.com/schedule-custom-interval"
900+
});
901+
902+
const {
903+
id: triggerId, // The unique ID of the deployed trigger
904+
endpoint_url: endpointUrl, // The endpoint URL to return to the user
905+
} = deployedTrigger;
906+
907+
// Parse and return the data you need
908+
```
909+
</Tabs.Tab>
910+
<Tabs.Tab>
911+
```bash
912+
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \
913+
-H "Content-Type: application/json" \
914+
-H "X-PD-Environment: {environment}" \
915+
-H "Authorization: Bearer {access_token}" \
916+
-d '{
917+
"external_user_id": "abc-123",
918+
"id": "schedule-custom-interval",
919+
"configured_props": {
920+
"cron": {
921+
"intervalSeconds": 900
922+
}
923+
},
924+
"webhook_url": "https://events.example.com/schedule-custom-interval"
925+
}'
926+
927+
# Parse and return the data you need
928+
```
929+
</Tabs.Tab>
930+
</Tabs>
931+
932+
##### Example response
933+
934+
```json
935+
{
936+
"id": "ti_aqGTJ2",
937+
"interval_seconds": 900,
938+
"cron": null,
939+
"timezone": "UTC",
940+
"schedule_changed_at": 1744508391,
941+
"created_at": 1744508391,
942+
"updated_at": 1744508391
943+
}
944+
```
945+
946+
#### New emails received
947+
Generate a unique email address for your customers to emit events to
948+
949+
<Tabs items={['Node.js', 'HTTP (cURL)']}>
950+
<Tabs.Tab>
951+
```javascript
952+
const { data: deployedTrigger } = await pd.deployTrigger({
953+
externalUserId: "abc-123",
954+
id: "email-new-email",
955+
webhookUrl: "https://events.example.com/email-new-email"
956+
});
957+
958+
const {
959+
id: triggerId, // The unique ID of the deployed trigger
960+
email_address: emailAddress, // The unique email address to return to the user
961+
} = deployedTrigger;
962+
963+
// Parse and return the data you need
964+
```
965+
</Tabs.Tab>
966+
<Tabs.Tab>
967+
```bash
968+
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \
969+
-H "Content-Type: application/json" \
970+
-H "X-PD-Environment: {environment}" \
971+
-H "Authorization: Bearer {access_token}" \
972+
-d '{
973+
"external_user_id": "abc-123",
974+
"id": "email-new-email",
975+
"webhook_url": "https://events.example.com/email-new-email"
976+
}'
977+
978+
# Parse and return the data you need
979+
```
980+
</Tabs.Tab>
981+
</Tabs>
982+
983+
##### Example response
984+
985+
```json
986+
{
987+
"id": "ei_QaJTb0",
988+
"email_address": "[email protected]",
989+
"created_at": 1744499847,
990+
"updated_at": 1744499847
991+
}
992+
```

0 commit comments

Comments
 (0)