For developers · about 25 min

Automating file transfers with APIs and webhooks: package creation to delivery

Connect package creation, authorized file movement and webhook processing with scoped credentials, verified events and a practical failure-handling checklist.

You end up with
A service principal with only the scopes it needs, a working CLI, and a script that creates packages and can be wired to a webhook for completion.
Plan
REST API and CLI are available from the Professional plan, per the pricing page.
Updated

Before you start

  • An administrator to create the API client, and a developer machine with the ripton CLI from your release archive.
  • Your workspace URL, written as https://ripton.example.com in the commands below.
  • A secret manager or environment-variable mechanism for the credential. The CLI deliberately has no secret flags because process arguments and shell history are visible to other users.

Steps

  1. Create an API client

    Admin · API clients

    Open Admin, then API clients, and create a client of type Service. Give it a name that says what it is for, for example 'nightly-export'.

  2. Grant only the scopes you need

    For creating packages and reading their state, choose Transfers write and Transfers read. Avoid All access. The backend enforces role, scope, ownership and resource grants; the CLI never elevates a credential.

  3. Store the credential

    Copy the secret into your secret manager the moment it is shown. Plan to rotate it and revoke it when the automation is retired.

  4. Configure the CLI

    Terminal

    Export the server URL and access token as environment variables, then run a read-only command to confirm access.

  5. Create a package from a script

    Call the packages endpoint with a title, recipients and optional expiry. The response includes the package ID; keep it for the follow-up calls. The files themselves move through the authorized transfer path, Ripton Desktop or an automation node, using the transfer spec for that package.

  6. Check state from the terminal

    List running transfers and the jobs overview to see what your automation created and where it stands.

  7. Close the loop with a webhook

    Subscribe to the supported lifecycle event you need. package.status_changed signals a status change, not necessarily completion. Inspect the payload and reconcile package state before triggering downstream processing.

Commands and reference

export RIPTON_SERVER=https://ripton.example.com
export RIPTON_ACCESS_TOKEN="$(secret-tool lookup ripton nightly-export)"   # or your secret manager's equivalent

ripton nodes list --query enabled=true
ripton transfers list --query status=running
ripton jobs overview
curl -fsS -X POST "$RIPTON_SERVER/api/v1/packages" \
  -H "Authorization: Bearer $RIPTON_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Integration evaluation","sender_name":"Integration service","recipients":[{"email":"ops@partner.example","type":"to"}]}'
EventMeaningDo not infer
package.createdA package record was createdFiles are uploaded or usable
package.status_changedThe package changed lifecycle statusEvery status transition means success
delivery.status_changedA delivery changed lifecycle statusThe recipient verified the downloaded files
package.external_file_downloadedExternal file-download activity was recordedThe entire business handoff is accepted

The current webhook worker sends X-RIPT-Webhook-Event-ID, X-RIPT-Webhook-Topic and X-RIPT-Webhook-Timestamp. When a signing secret is configured, X-RIPT-Webhook-Signature is sha256= followed by the hex HMAC-SHA256 of timestamp + a literal period + the raw request body. Configure signing for the integration and require a valid signature at your receiver.

  1. 1Preserve the raw request bytes; verify the signature using a timing-safe comparison before trusting the payload. Do not parse and reserialize before verification.
  2. 2Apply an agreed timestamp freshness policy and retain event IDs to handle duplicate delivery attempts safely.
  3. 3Persist accepted work durably before returning a successful response. The sender treats HTTP 2xx as delivered, not as proof that your downstream job succeeded.
  4. 4Process asynchronously, record package/event IDs and reconcile failures against the source state. Do not assume exactly-once processing or a particular retry window.
  5. 5Test invalid signatures, repeated IDs, non-completion status changes and receiver failure in a non-production environment.

How you know it worked

  • A read operation within the credential's scopes succeeds; an operation outside them is refused. Listing nodes requires its own applicable permission.
  • The package created by the script appears in the admin Packages page with the expected title and recipients.
  • Credential rotation and revocation behave as documented for the installed release; test existing access tokens separately from newly issued tokens.

If something is off

What you seeWhat to do
401 or 403 from every callThe token is missing or the client lacks the scope. Check RIPTON_ACCESS_TOKEN is set in the same shell and that the client has the scope for the operation.
The package is created but stays in uploadingCreating the package records it; the bytes still have to move. Confirm the automation host runs the transfer step with the package's transfer spec, and watch the transfer in Admin, then Transfers.
Rate limitedPoll less often, or replace polling with a webhook subscription.