{ "openapi": "3.0.0", "info": { "title": "Triggers API", "version": "1.0.0" }, "servers": [ { "url": "https://actionkit.useparagon.com", "description": "US Cloud" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Your [Paragon User Token](/getting-started/installing-the-connect-sdk#setup) (JWT), which you can generate using your project's signing keys." } }, "schemas": { "TriggerParameter": { "type": "object", "properties": { "id": { "type": "string", "description": "The parameter key which should be passed to `parameters` in [Subscribe to a Trigger](/actionkit/triggers/api-reference/subscribe-to-trigger) when providing a value." }, "type": { "type": "string", "description": "The input type. See the full list of possible types in [Input Types](/actionkit/schema-formats#overview)." }, "label": { "type": "string", "description": "The parameter label" }, "required": { "type": "boolean", "description": "Whether this parameter is required" } } }, "TriggerDefinition": { "type": "object", "properties": { "type": { "type": "string", "description": "The trigger type identifier used to create a subscription. Custom Webhooks are prefixed with `[INTEGRATION]_CUSTOM_[name]`.", "example": "SALESFORCE_TRIGGER_RECORD_CREATED" }, "triggerModel": { "type": "string", "enum": ["POLLING", "WEBHOOK"], "description": "The trigger model (POLLING or WEBHOOK)" }, "title": { "type": "string", "description": "The trigger title from the frontend config", "example": "New Record" }, "description": { "type": "string", "description": "The trigger description from the frontend config", "example": "Trigger when a new record is created in Salesforce" }, "parameters": { "type": "array", "description": "Configuration parameters for this trigger, which can be rendered as inputs for your user. Learn more in [User Configuration](/actionkit/triggers/user-configuration).", "items": { "$ref": "#/components/schemas/TriggerParameter" } } }, "required": [ "type", "triggerModel", "title", "description", "parameters" ] }, "WebhookOverride": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The webhook URL to receive trigger events", "example": "https://example.com" }, "headers": { "type": "object", "description": "HTTP headers (case-insensitive) to pass with each webhook request", "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "description": "JSON object to include with webhook payload. This will be passed in the `triggerSubscriptionMetadata` field of incoming webhook events.", "additionalProperties": true } }, "required": ["url"] }, "TriggerSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The subscription ID", "example": "" }, "type": { "type": "string", "description": "The trigger type", "example": "SALESFORCE_TRIGGER_RECORD_CREATED" }, "parameters": { "type": "object", "description": "The trigger configuration parameters", "additionalProperties": true, "example": { "recordType": "Opportunity" } }, "status": { "type": "string", "enum": ["ACTIVE", "ERRORED"], "description": "ACTIVE: currently receiving events. ERRORED: errors checking for records or repeated webhook delivery issues resulted in the trigger being disabled." }, "error": { "type": "string", "description": "The reason for an error (only present when status is ERRORED)", "example": "Failed to check for new records after repeated failures. Last error: Request failed with 500 { ... error info ... }" }, "dateCreated": { "type": "string", "format": "date-time", "description": "The date the subscription was created", "example": "2025-05-31T00:00:00Z" }, "dateLastReceivedEvent": { "type": "string", "format": "date-time", "description": "For polling triggers: date we last checked for new records. For webhook triggers: date we last received a webhook event.", "example": "2025-05-31T00:00:00Z" }, "credentialId": { "type": "string", "format": "uuid", "description": "The credential ID associated with this subscription", "example": "" }, "webhookOverride": { "$ref": "#/components/schemas/WebhookOverride", "description": "Undefined if no webhook override is set for this subscription" } }, "required": [ "id", "type", "parameters", "status", "dateCreated", "dateLastReceivedEvent", "credentialId" ] }, "Error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "status": { "type": "integer", "description": "HTTP status code" } } }, "GetTriggerExamplesRequest": { "type": "object", "properties": { "type": { "type": "string", "description": "The trigger type identifier (e.g. SALESFORCE_TRIGGER_RECORD_CREATED).", "example": "SALESFORCE_TRIGGER_RECORD_CREATED" }, "integration": { "type": "string", "description": "The integration name for the trigger (e.g. salesforce, hubspot).", "example": "salesforce" }, "parameters": { "type": "object", "description": "Trigger configuration parameters, same shape as `parameters` in [Subscribe to a Trigger](/actionkit/triggers/api-reference/subscribe-to-trigger).", "additionalProperties": true, "example": { "recordType": "Opportunity" } } }, "required": ["type", "integration"] } }, "parameters": { "ProjectId": { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Your Paragon Project ID" } }, "SubscriptionId": { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The trigger subscription ID" } }, "IntegrationsFilter": { "name": "integrations", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by specific integrations that the user has connected. Comma-separated list.", "example": "salesforce,hubspot" } }, "LimitToAvailable": { "name": "limit_to_available", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "description": "If `true` (default), only triggers for integrations the user has **connected** are returned.\n\nSet to `false` to return triggers for all integrations enabled on the project, regardless of whether the user has connected them." } }, "CredentialHeader": { "name": "X-Paragon-Credential", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Specify a credential ID when multiple accounts are connected for the same integration" } } } }, "paths": { "/projects/{project_id}/triggers": { "get": { "summary": "List Available Triggers", "description": "Return all available triggers, including custom triggers, and their configuration options as definitions/schemas.", "operationId": "listAvailableTriggers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IntegrationsFilter" }, { "$ref": "#/components/parameters/LimitToAvailable" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "triggers": { "type": "object", "description": "A map of integrations with their available triggers", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerDefinition" } } } } }, "example": { "triggers": { "salesforce": [ { "type": "SALESFORCE_TRIGGER_RECORD_CREATED", "triggerModel": "POLLING", "title": "New Record", "description": "Trigger when a new record is created in Salesforce", "parameters": [ { "id": "recordType", "type": "TEXT_NO_VARS", "label": "Record Type", "required": true } ] } ] } } } } } } } }, "/projects/{project_id}/triggers/examples": { "post": { "summary": "Get Example Payload", "description": "Get example records for a trigger. Use this to preview what an incoming event payload could look like.", "operationId": "getExamplePayload", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/CredentialHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTriggerExamplesRequest" }, "example": { "type": "SALESFORCE_TRIGGER_RECORD_CREATED", "integration": "salesforce", "parameters": { "recordType": "Opportunity" } } } } }, "responses": { "200": { "description": "Success - Returns array of example records that could be returned from the trigger", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Example records that could be returned from the trigger", "additionalProperties": true } }, "example": [ { "id": "001xx000003DHP0AAO", "name": "Sample Opportunity", "amount": 50000, "stage": "Prospecting", "closeDate": "2025-12-31" } ] } } } } } }, "/projects/{project_id}/trigger-subscriptions": { "get": { "summary": "List Subscribed Triggers", "description": "Return all trigger subscriptions for this user.\n\nIf `X-Paragon-Credential` is specified, only that credential's trigger subscriptions are listed. Otherwise, all credentials' trigger subscriptions are listed.", "operationId": "listSubscribedTriggers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IntegrationsFilter" }, { "$ref": "#/components/parameters/CredentialHeader" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["ACTIVE", "ERRORED"], "description": "Filter subscriptions to only active or errored (default behavior is to include all)" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter subscriptions to a specific type of Trigger", "example": "SALESFORCE_TRIGGER_RECORD_CREATED" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "triggers": { "type": "object", "description": "A map of integrations with their subscribed triggers", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerSubscription" } } } } }, "example": { "triggers": { "salesforce": [ { "id": "", "type": "SALESFORCE_TRIGGER_RECORD_CREATED", "parameters": { "recordType": "Opportunity" }, "status": "ACTIVE", "dateCreated": "2025-05-31T00:00:00Z", "dateLastReceivedEvent": "2025-05-31T00:00:00Z", "credentialId": "", "webhookOverride": { "url": "https://override.com" } }, { "id": "", "type": "SALESFORCE_TRIGGER_RECORD_CREATED", "parameters": { "recordType": "Opportunity" }, "status": "ERRORED", "error": "Failed to check for new records after repeated failures. Last error: Request failed with 500 { ... error info ... }", "dateCreated": "2025-05-31T00:00:00Z", "dateLastReceivedEvent": "2025-05-31T00:00:00Z", "credentialId": "" } ] } } } } }, "400": { "description": "Bad Request - X-Paragon-Credential is specified but integrations is also provided (these options cannot be passed together)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Subscribe to Trigger", "description": "Create a trigger subscription for this user/credential. Multiple subscriptions can be set up for the same trigger and credential.\n\nResponds only when the trigger subscription is created and set up, ready to receive events.", "operationId": "subscribeToTrigger", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/CredentialHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "type": "string", "description": "The integration name for the trigger (e.g., salesforce, hubspot)", "example": "salesforce" }, "type": { "type": "string", "description": "The trigger type to subscribe to", "example": "SALESFORCE_TRIGGER_RECORD_CREATED" }, "parameters": { "type": "object", "description": "The parameter values to configure this trigger with. If you are collecting these parameters from your users, learn more about rendering UI elements for parameters in [User Configuration](/actionkit/triggers/user-configuration).", "additionalProperties": true, "example": { "recordType": "Opportunity" } }, "webhookOverride": { "$ref": "#/components/schemas/WebhookOverride", "description": "Optional. If defined, must have `url` specified." } }, "required": ["integration", "type", "parameters"] }, "example": { "integration": "salesforce", "type": "SALESFORCE_TRIGGER_RECORD_CREATED", "parameters": { "recordType": "Opportunity" }, "webhookOverride": { "url": "https://example.com", "headers": {}, "metadata": {} } } } } }, "responses": { "200": { "description": "Success - Returns the created trigger subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerSubscription" }, "example": { "id": "", "type": "SALESFORCE_TRIGGER_RECORD_CREATED", "parameters": { "recordType": "Opportunity" }, "status": "ACTIVE", "dateCreated": "2025-05-31T00:00:00Z", "dateLastReceivedEvent": "2025-05-31T00:00:00Z", "credentialId": "", "webhookOverride": { "url": "https://example.com" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingParameters": { "value": { "message": "Required trigger parameters are missing: objectType, filterFormula", "status": 400 } }, "multipleCredentials": { "value": { "message": "More than one account connected for salesforce. Pass X-Paragon-Credential: [Credential UUID] in headers to select an account to use when subscribing to this trigger.", "status": 400 } }, "missingWebhookUrl": { "value": { "message": "webhookOverride.url is required when webhookOverride is defined", "status": 400 } } } } } } } } }, "/projects/{project_id}/trigger-subscriptions/{subscription_id}": { "delete": { "summary": "Unsubscribe from Trigger", "description": "Removes a trigger subscription for this user by ID.\n\nResponds only when the trigger subscription has been completely torn down or there is an error.", "operationId": "unsubscribeFromTrigger", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SubscriptionId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "warning": { "type": "string", "description": "Present when webhook tear down fails", "example": "Integration webhook failed to tear down. Check the connected account and manually remove any old webhooks if necessary. The webhook URL was: https://example.com/webhook" } }, "required": ["success"] }, "examples": { "success": { "value": { "success": true } }, "successWithWarning": { "value": { "success": true, "warning": "Integration webhook failed to tear down. Check the connected account and manually remove any old webhooks if necessary. The webhook URL was: https://example.com/webhook" } } } } } } } }, "patch": { "summary": "Update Trigger Subscription", "description": "Update a trigger subscription by ID, for changing the parameters or webhook override URL.\n\nAll keys are optional: any keys not provided will not be changed. Parameters are shallow-merged with the patch payload:\n- Omitted keys are unchanged\n- Provided keys overwrite\n- Null removes keys\n- Arrays replace in full, not merge", "operationId": "updateTriggerSubscription", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/SubscriptionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parameters": { "type": "object", "description": "The trigger configuration parameters to update. Omitted keys unchanged, provided keys overwrite, null removes keys.", "additionalProperties": true }, "webhookOverride": { "description": "Update or clear (with null) the webhook override", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/WebhookOverride" } ] } }, "example": { "parameters": { "objectType": "Opportunity", "filterFormula": null }, "webhookOverride": null } } } } }, "responses": { "200": { "description": "Success - Returns the updated trigger subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerSubscription" }, "example": { "id": "", "type": "SALESFORCE_TRIGGER_RECORD_CREATED", "parameters": { "objectType": "Opportunity" }, "status": "ACTIVE", "dateCreated": "2025-05-31T00:00:00Z", "dateLastReceivedEvent": "2025-05-31T00:00:00Z", "credentialId": "" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "`type` cannot be updated in a trigger subscription. Instead, unsubscribe from this trigger and create a new subscription with the desired `type`.", "status": 400 } } } } } } } } }