Working With System-to-Person Webhooks

The System-to-Person API provides webhook subscriptions to send notifications about transfer events and file operations. Once a webhook subscription is enabled, you can integrate an application with your portal to receive portal event notifications.

System-to-Person provides webhook subscriptions for:

Transfers
Token Actions
File Operations

When creating a new portal subscription using the API, or adding notifications as part of token generation, the request body requires a valid URL to receive webhooks.

If notifications are enabled at multiple levels, you may receive duplicate notifications for the same transfer event or file operation.

Once the subscription is created, webhooks are sent to the URL as a JSON object.

Note: In order to use this API resource, your account requires a System-to-Person API subscription.

Webhook Content

Transfer webhooks are sent after the completion of an upload or download, and include a payload, eventType and timestamp. If a transfer is successful but all files are skipped, no webhook will be sent.

A receiving service must be available and ready to receive webhook messages. If a webhook message is not immediately received by your service, two additional attempts are made at five minute intervals.

Note: Webhook responses must be received within 15 seconds. Failed webhook responses cannot be later retrieved.

Payload

A webhook payload includes the Operation Details for the transfer and Portal Details of the portal used to conduct the transfer.

For example, if a transfer has two parts, the response would list totalParts: 2. Each piece of the transfer has a partNumber which tells you when each part was transferred, as each part will return its own response.

Operation Details

The payload for transfer and token events includes details about the package including the package ID, when it was created, the files and folders included in the package, and the size of each file transferred in that package.

The webhook response also includes the user's email address, the transferId, the total number of event parts, and the event part being processed. Events are broken into multiple parts when a transfer includes a large number of files.

Note: Transfer events may have multiple parts. You receive webhook notifications for each package part when the transfer completes.

The payload for file operation events includes the file or folder names being renamed, moved, deleted, or created.

Portal Details

The payload also includes portal details, including your portal's unique ID, portal name, URL, portal type, and type of authentication used to log into that portal.

Storage details outline the specific storage configuration for the portal event. The storage details array contains information about that portal's storage. These include its unique ID, storage type, and the configuration details for your storage, and the location where the transferred files are stored.

Transfer Events

Transfer event webhooks contain information about files transferred to and from storage using the portal or via System-to-Person token events. Webhooks related to transfers include the relevant files involved in the transfer, details about the portal, as well as details about the storage destination or origin.

Token Events

Token event webhooks contain information about a transfer using a package token, which is a URL containing a token used to create specific transfers.

Whenever a package token is used or redeemed, the webhook response contains information about the event, including the event type and timestamp, as well as the token ID, grants, and details about the user, portal ID, and transfer ID.

Token event subscription webhooks are sent on package uploads, downloads, and token redemptions.

File Events

File event webhooks contain information about file operations performed on the portal.

Whenever a file or folder is renamed, moved, deleted, or a new folder is created, a webhook response containing information about the operation, including the event type, timestamp, and relevant files.

Webhook Event List

Note: Auto-delivery transfers do not send webhooks.

Event	Action
`package.upload.complete`	When a package upload completes.
`package.upload.canceled`	When a package upload is canceled.
`package.upload.failed`	When a package upload fails.
`package.download.complete`	When a package download completes.
`package.download.canceled`	When a package download is canceled.
`package.download.failed`	When a package download fails.
`tokenRedeemed`	When a package token is redeemed by the recipient.
`file.rename.complete`	When a file in the portal is successfully renamed.
`file.rename.failed`	When a file in the portal cannot be renamed.
`file.move.complete`	When a file in the portal is successfully moved to a new file path.
`file.move.failed`	When a file in the portal cannot be moved to a new file path.
`file.delete.complete`	When a file in the portal is successfully deleted.
`file.delete.failed`	When a file in the portal cannot be deleted.
`folder.creation.complete`	When a new folder is created in the portal.
`folder.creation.failed`	When a new folder cannot be created in the portal.

Example Webhook Responses

Transfer Events

Completed Transfer

Copy


{
  "eventType": "package.upload.complete",
  "timestamp": "2018-03-02T19:20:50.52.000Z",
  "payload": {
    "packageDetails": {
      "id": "m42kqJGGOyGagudcFANQIR",
      "createdOn": "2018-03-02T19:20:50.52.000Z",
      "files": {
        "files": [
          {
            "path": "example_folder/example_file.mp4",
            "isDirectory": false,
            "size": 200000
          }
        ]
      }
    },
    "portalDetails": {
      "id": "12345678-ABCD-WXYZ-DCBA-12345c678987",
      "name": "Example Portal",
      "url": "new-portal.mediashuttle.com",
      "type": "share",
      "createdOn": "2017-04-20T20:20:15.513Z",
      "lastModifiedOn": "2018-07-10T19:24:52.511Z",
      "authentication": {
        "mediaShuttle": true,
        "saml": false
      },
      "storage": [
        {
          "id": "87654321-DCBA-ZYXW-ABCD-127371111987",
          "type": "s3",
          "configuration": {
            "hostName": "my.example.com",
            "repositoryPath": "/root/path/portalrepo",
            "bucket": "bucket-name",
            "container": "azure-container",
            "filePrefix": "path/prefix"
          }
        }
      ]
    },
    "userEmail": "user@example.com",
    "transferId": "35460d47-019b-4e06-8108-18343b235108",
    "totalParts": 1,
    "partNumber": 1,
    "deliveryRequestTokenId": "rL7riSfExq3NCijnYA7xer"
  }
}

The deliveryRequestTokenId key is only included when a user completes a file transfer request from a Send portal or Share portal.

Canceled Transfer

Copy


{
  "eventType": "package.upload.canceled",
  "timestamp": "2018-03-02T19:20:50.52.000Z",
  "payload": {
    "packageDetails": {
      "id": "m42kqJGGOyGagudcFANQIR",
      "createdOn": "2018-03-02T20:50:52.000Z",
      "files": [
        {
          "path": "example_folder/example_file.mp4",
          "isDirectory": false,
          "size": 200000
        }
      ]
    },
    "portalDetails": {
      "id": "12345678-ABCD-WXYZ-DCBA-12345c678987",
      "name": "Example Portal",
      "url": "new-portal.mediashuttle.com",
      "type": "share",
      "createdOn": "2017-04-20T20:20:15.513Z",
      "lastModifiedOn": "2018-07-10T19:24:52.511Z",
      "authentication": {
        "mediaShuttle": true,
        "saml": false
      },
      "storage": [
        {
          "id": "87654321-DCBA-ZYXW-ABCD-127371111987",
          "storageType": "s3",
          "configuration": {
            "hostName": "my.example.com",
            "repositoryPath": "/root/path/portalrepo",
            "bucket": "bucket-name",
            "container": "azure-container",
            "filePrefix": "path/prefix"
          }
        }
      ]
    },
    "userEmail": "user@example.com",
    "transferId":
     "35460d47-019b-4e06-8108-18343b235109",
    "totalParts": 1,
    "partNumber": 1,
    "deliveryRequestTokenId": "rL7riSfExq3NCijnYA7xer"
  }
}

Depending on the transfer progress at the time an upload fails or is canceled, some of the files included in a package may already have transferred. If an upload fails before any files could transfer, files will contain an empty array.

The deliveryRequestTokenId key is only included when a user cancels a transfer based on a file request from a Send portal or Share portal.

Failed Transfer

Copy


{
  "eventType": "package.upload.failed",
  "timestamp": "2018-03-02T19:20:50.52.000Z",
  "payload": {
    "packageDetails": {
      "id": "m42kqJGGOyGagudcFANQIR",
      "createdOn": "2018-03-02T20:50:52.000Z",
      "files": [
        {
          "path": "example_folder/example_file.mp4",
          "isDirectory": false,
          "size": 200000
        }
      ]
    },
    "portalDetails": {
      "id": "12345678-ABCD-WXYZ-DCBA-12345c678987",
      "name": "Example Portal",
      "url": "new-portal.mediashuttle.com",
      "type": "share",
      "createdOn": "2017-04-20T20:20:15.513Z",
      "lastModifiedOn": "2018-07-10T19:24:52.511Z",
      "authentication": {
        "mediaShuttle": true,
        "saml": false
      },
      "storage": [
        {
          "id": "87654321-DCBA-ZYXW-ABCD-127371111987",
          "storageType": "s3",
          "configuration": {
            "hostName": "my.example.com",
            "repositoryPath": "/root/path/portalrepo",
            "bucket": "bucket-name",
            "container": "azure-container",
            "filePrefix": "path/prefix"
          }
        }
      ]
    },
    "userEmail": "user@example.com",
    "transferId":
     "35460d47-019b-4e06-8108-18343b235109",
    "totalParts": 1,
    "partNumber": 1
  }
}

Note: Depending on the transfer progress at the time an upload fails or is cancelled, some of the files included in a package may already have transferred. If an upload fails before any files could transfer, files will contain an empty array.

The deliveryRequestTokenId key is only included when uploading files in response to a request from a Send portal or Share portal but the transfer fails.

Example File Operation Webhook Responses

Completed Rename

Copy

{
  "payload": {
    "sources": [
      {
        "isDirectory": false,
        "filePath": "example.mp4"
      }
    ],
    "destination": "july_example.mp4",
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "file.rename.complete",
  "timestamp": "2019-07-22T14:18:56.972Z"
}

Failed Rename

Copy

{
  "payload": {
    "sources": [
      {
        "isDirectory": false,
        "filePath": "example.mp4"
      }
    ],
    "destination": "july_example.mp4",
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "file.rename.failed",
  "timestamp": "2019-07-23T15:28:35.600Z"
}

Completed Move

Copy

{
  "payload": {
    "sources": [
      {
        "isDirectory": false,
        "filePath": "example.mp4"
      }
    ],
    "destination": "/",
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "file.move.complete",
  "timestamp": "2019-07-22T14:18:56.972Z"
}

Failed Move

Copy

{
  "payload": {
    "sources": [
      {
        "isDirectory": false,
        "filePath": "example.mp4"
      }
    ],
    "destination": "invalidFolder/invalidSubfolder",
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "file.move.failed",
  "timestamp": "2019-07-23T15:28:35.600Z"
}

Completed File Deletion

Copy

{
  "payload": {
    "sources": [
      {
        "isDirectory": false,
        "filePath": "path/to/file.mp4"
      }
    ],
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "file.delete.complete",
  "timestamp": "2019-07-16T14:20:03.630Z"
}

Failed File Deletion

Copy

{
  "payload": {
    "sources": [
      {
        "isDirectory": false,
        "filePath": "path/to/file.mp4"
      }
    ],
    "failedSources": [
      {
        "isDirectory": true,
        "filePath": "path/to/invalidFilename.mp4"
      }
    ],
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "file.delete.failed",
  "timestamp": "2019-07-16T14:20:03.630Z"
}

Completed Folder Creation

Copy

{
  "payload": {
    "destination": "folder/subfolder",
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "folder.create.complete",
  "timestamp": "2019-07-23T13:35:52.257Z"
}

Failed Folder Creation

Copy

{
  "payload": {
    "destination": "folder/subfolder",
    "portalId": "12345678-abcd-dcba-4321-123456789abc",
    "userEmail": "user@example.com"
  },
  "eventType": "folder.create.complete",
  "timestamp": "2019-07-23T13:35:52.257Z"
}