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:

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.

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 cancelled.
package.upload.failed When a package upload fails.
package.download.complete When a package download completes.
package.download.canceled When a package download is cancelled.
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

{
  "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
  }
}

Canceled Transfer

{
  "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
  }
}

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.

Failed Transfer

{
  "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.

Example File Operation Webhook Responses

Completed Rename

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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"
}