[43.2 and later] Salesforce Listener Block Deprecation

The legacy Salesfroce Listener Block is no longer supported and should not be used

You can integrate Salesforce with Hyperscience using the approach that best fits your Salesforce instance, security model, and operating practices. Hyperscience does not require a specific Salesforce-side implementation.

The supported contract is the Hyperscience Submission API endpoint: Salesforce, middleware, or another customer-managed integration layer should create submissions by calling POST /api/v5/submissions.

For the complete API contract, request parameters, authentication guidance, response fields, and supported file stores, see the Hyperscience API documentation.

Authentication to Hyperscience

The customer-managed integration must authenticate to Hyperscience before it can create submissions. Machine-to-machine authentication with OAuth 2.0 is required for SaaS deployments and strongly recommended for on-premises deployments where available.

At a high level, the integration obtains an access token from the Hyperscience local identity provider, then includes that access token in the Authorization header when calling POST /api/v5/submissions.

For setup steps and supported OAuth flows, see Machine to Machine (M2M) Authentication with OAuth 2.0.

What Hyperscience expects

Any Salesforce integration should send documents to Hyperscience through the Submission Creation endpoint. At a high level, the integration should:

1. Authenticate to Hyperscience using a supported production authentication method.

2. Create a submission with POST /api/v5/submissions .

3. Provide the document file either as uploaded file content or as a supported file reference.

4. Include flow-selection or routing parameters, such as flow_uuid, when applicable.

5. Include optional metadata or external identifiers when useful for downstream tracking.

Hyperscience receives the submission, retrieves or decodes the submitted file, and starts processing it according to the target flow configuration.

Integration flexibility

You may choose any Salesforce-side pattern that can produce a valid Submission API request. For example, an implementation might use one of the following patterns:

The diagram below shows common integration patterns. It is an example architecture only; you are not required to implement it.

File transfer and security

You should choose a file-transfer method that matches your security requirements and file size constraints.

Files can be uploaded directly to the Submission API endpoint when the integration has access to the file content.

Inline or encoded file content can be useful for smaller files, but you should validate this against the current limits of your Salesforce implementation. Base64 encoding increases payload size, and Salesforce-side automation can be constrained by applicable platform limits such as Apex memory and outbound request limits. For larger files or when the encoded payload approaches these limits, use direct file upload or provide a secure file URL instead.

Files can also be provided by URL when the file remains in Salesforce or another customer-managed system. When the URL requires authentication, the integration should provide the necessary information for the Hyperscience HTTP Downloader to retrieve the file securely, such as an OAuth bearer token configuration supported by the flow.

Submission API authentication and file download authentication are separate. Authenticating to POST /api/v5/submissionsallows the integration to create a submission in Hyperscience. If the submission includes a protected file_url, Hyperscience must also be able to authenticate back to the file source when the HTTP Downloader fetches the file.

For protected HTTP or HTTPS file URLs, configure OAuth client credentials on the Submission Initialization Block:

At download time, the HTTP Downloader requests an OAuth access token using those credentials and sends the file-download request with Authorization: Bearer <access_token>. This header lets you submit authenticated Salesforce file URLs, or other protected HTTP/HTTPS URLs, without exposing public file links.

Temporary public URLs should only be used when they match your security requirements. When used, they should be short-lived and cleaned up after submission.

A pre-signed URL or other temporary public file_url can be used as a fallback when authenticated download is not available, but it is not equivalent to authenticated retrieval. Any party with access to the URL may be able to download the file until the URL expires or is revoked. Use short expirations, least-privilege access, and cleanup controls if this pattern is required.

Migration guidance

Customers using the legacy Salesforce Listener connector should replace it with a customer-managed integration that calls the Hyperscience Submission API endpoint directly.