diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index 1ce70efdce43b..2c046d72008da 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -2011,6 +2011,10 @@ curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run #### Deploy a trigger + +See [here](/connect/components/#deploying-triggers) for more info on supported trigger types with example payloads + + Deploy a trigger component that will emit events to a webhook or workflow for a Pipedream Connect user. ```text @@ -2492,14 +2496,14 @@ curl -X GET \ Retrieve a single deployed trigger for a given user. ```text -GET /deployed-triggers/{deployed_component_id}/ +GET /deployed-triggers/{deployed_trigger_id}/ ``` ##### Path parameters -`dcid` **string** +`deployed_trigger_id` **string** -The deployed component ID for the trigger you'd like to retrieve. +The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`). ##### Query parameters @@ -2590,7 +2594,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ curl -X GET \ -G \ - "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/" \ + "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -H "x-pd-environment: development" \ @@ -2677,14 +2681,14 @@ curl -X GET \ Delete deployed trigger for a given user. ```text -DELETE /deployed-triggers/{deployed_component_id}/ +DELETE /deployed-triggers/{deployed_trigger_id}/ ``` ##### Path parameters -`dcid` **string** +`deployed_trigger_id` **string** -The deployed component ID for the trigger you'd like to retrieve. +The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`). ##### Query parameters @@ -2768,7 +2772,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ curl -X DELETE \ -G \ - "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/" \ + "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -H "x-pd-environment: development" \ @@ -2787,14 +2791,14 @@ Pipedream returns a `204 No Content` response on successful deletion Retrieve a list of the last events that a deployed trigger emitted. ```text -GET /deployed-triggers/{deployed_component_id}/events/ +GET /deployed-triggers/{deployed_trigger_id}/events/ ``` ##### Path parameters -`dcid` **string** +`deployed_trigger_id` **string** -The deployed component ID for the trigger you'd like to retrieve. +The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`). ##### Query parameters @@ -2889,7 +2893,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ curl -X GET \ -G \ - "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/events" \ + "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/events" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -H "x-pd-environment: development" \ @@ -2984,14 +2988,14 @@ curl -X GET \ Retrieve the list of webhook URLs listening to a deployed trigger. ```text -GET /deployed-triggers/{deployed_component_id}/webhooks/ +GET /deployed-triggers/{deployed_trigger_id}/webhooks/ ``` ##### Path parameters -`dcid` **string** +`deployed_trigger_id` **string** -The deployed component ID for the trigger you'd like to retrieve. +The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`). ##### Query parameters @@ -3081,7 +3085,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ curl -X GET \ -G \ - "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \ + "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/webhooks/" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -H "x-pd-environment: development" \ @@ -3105,14 +3109,14 @@ curl -X GET \ Update the list of webhook URLs that will listen to a deployed trigger. ```text -PUT /deployed-triggers/{deployed_component_id}/webhooks/ +PUT /deployed-triggers/{deployed_trigger_id}/webhooks/ ``` ##### Path parameters -`dcid` **string** +`deployed_trigger_id` **string** -The deployed component ID for the trigger you'd like to retrieve. +The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`). ##### Query parameters @@ -3220,7 +3224,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ # This request will update the list of webhook URLs listening to the specified deployed trigger. curl -X PUT \ - "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \ + "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/webhooks/" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -H "x-pd-environment: development" \ @@ -3244,14 +3248,14 @@ curl -X PUT \ Retrieve the list of workflow IDs listening to a deployed trigger. ```text -GET /deployed-triggers/{deployed_component_id}/workflows/ +GET /deployed-triggers/{deployed_trigger_id}/workflows/ ``` ##### Path parameters -`dcid` **string** +`deployed_trigger_id` **string** -The deployed component ID for the trigger you'd like to retrieve. +The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`). ##### Query parameters @@ -3341,7 +3345,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ curl -X GET \ -G \ - "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/workflows/" \ + "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/workflows/" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -H "x-pd-environment: development" \ @@ -3366,14 +3370,14 @@ curl -X GET \ Update the list of workflows that will listen to a deployed trigger. ```text -PUT /deployed-triggers/{deployed_component_id}/workflows/ +PUT /deployed-triggers/{deployed_trigger_id}/workflows/ ``` ##### Path parameters -`dcid` **string** +`deployed_trigger_id` **string** -The deployed component ID for the trigger you'd like to retrieve. +The deployed trigger ID for the trigger you'd like to retrieve (ex, `dc_xxxxxxx`, `hi_xxxxxxx`, `ti_xxxxxxx`, or `ei_xxxxxxx`). ##### Query parameters @@ -3482,7 +3486,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ # This request will update the list of webhook URLs listening to the specified deployed trigger. curl -X PUT \ - "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \ + "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{deployed_trigger_id}/webhooks/" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -H "x-pd-environment: development" \ diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index 641a6693c50cd..f4257be884b9d 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -812,3 +812,181 @@ retrieve, or update the source in the future. Refer to the [full Connect API reference](/connect/api#components) for questions and additional examples. + +## Deploying triggers + +These are 2 categories of triggers you can deploy on behalf of your end users: +- [App-based event sources](#app-based-event-sources) +- [Native triggers](#native-triggers) + + +Refer to the [full Connect API reference](/connect/api/#deploy-a-trigger) to list, retrieve, delete, and manage triggers for your user + + +### App-based event sources +- 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) +- 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 +- Refer to the [quickstart above](#deploying-a-source) to get started + +### Native triggers +- 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** +- Because these triggers don't use a connected account from your end users, APIs to deploy and manage them are slightly different (see below) + +#### HTTP Webhook +Generate a unique HTTP webhook URL for your end users to configure in any other upstream service. + + + +```javascript +const { data: deployedTrigger } = await pd.deployTrigger({ + externalUserId: "abc-123", + id: "http-new-requests", + webhookUrl: "https://events.example.com/http-new-requests" +}); + +const { + id: triggerId, // The unique ID of the deployed trigger + endpoint_url: endpointUrl, // The endpoint URL to return to the user +} = deployedTrigger; + +// Parse and return the data you need +``` + + +```bash +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: {environment}" \ + -H "Authorization: Bearer {access_token}" \ + -d '{ + "external_user_id": "abc-123", + "id": "http-new-requests", + "webhook_url": "https://events.example.com/http-new-requests" + }' + +# Parse and return the data you need +``` + + + +##### Example response + +```json +{ + "id": "hi_zbGHMx", + "key": "xxxxxxxxxx", + "endpoint_url": "http://xxxxxxxxxx.m.pipedream.net", + "custom_response": true, + "created_at": 1744508049, + "updated_at": 1744508049 +} +``` + +#### Schedule +Deploy a timer to act as a cron job that will emit an event on a custom schedule you or your users define. + + + +```javascript +const { data: deployedTrigger } = await pd.deployTrigger({ + externalUserId: "abc-123", + id: "schedule-custom-interval", + configuredProps: { + "cron": { + "intervalSeconds": 900 + } + }, + webhookUrl: "https://events.example.com/schedule-custom-interval" +}); + +const { + id: triggerId, // The unique ID of the deployed trigger + endpoint_url: endpointUrl, // The endpoint URL to return to the user +} = deployedTrigger; + +// Parse and return the data you need +``` + + +```bash +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: {environment}" \ + -H "Authorization: Bearer {access_token}" \ + -d '{ + "external_user_id": "abc-123", + "id": "schedule-custom-interval", + "configured_props": { + "cron": { + "intervalSeconds": 900 + } + }, + "webhook_url": "https://events.example.com/schedule-custom-interval" + }' + +# Parse and return the data you need +``` + + + +##### Example response + +```json +{ + "id": "ti_aqGTJ2", + "interval_seconds": 900, + "cron": null, + "timezone": "UTC", + "schedule_changed_at": 1744508391, + "created_at": 1744508391, + "updated_at": 1744508391 +} +``` + +#### New emails received +Generate a unique email address for your customers to emit events to + + + +```javascript +const { data: deployedTrigger } = await pd.deployTrigger({ + externalUserId: "abc-123", + id: "email-new-email", + webhookUrl: "https://events.example.com/email-new-email" +}); + +const { + id: triggerId, // The unique ID of the deployed trigger + email_address: emailAddress, // The unique email address to return to the user +} = deployedTrigger; + +// Parse and return the data you need +``` + + +```bash +curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \ + -H "Content-Type: application/json" \ + -H "X-PD-Environment: {environment}" \ + -H "Authorization: Bearer {access_token}" \ + -d '{ + "external_user_id": "abc-123", + "id": "email-new-email", + "webhook_url": "https://events.example.com/email-new-email" + }' + +# Parse and return the data you need +``` + + + +##### Example response + +```json +{ + "id": "ei_QaJTb0", + "email_address": "xxxxxxxxxx@upload.pipedream.net", + "created_at": 1744499847, + "updated_at": 1744499847 +} +``` \ No newline at end of file