Working With System-to-Person Webhooks

Signiant’s System-to-Person API allows you to create webhooks that authorize your application to receive information about portal events.

Webhooks send subscription updates to a URL when a transfer finishes, or a file operation is performed on the portal.

When creating a new portal subscription via the API, your request body must include a URL that will receive webhooks. Once the subscription is created, information about your transfers is sent to the URL in the form of a JSON object.

System-to-Person webhooks are available for:

For more information on creating a subscription, see the Media Shuttle System-to-Person API Documentation on SwaggerHub.

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

Portal Event Subscriptions

Portal event subscriptions allow you to retrieve details about transfer packages being transferred using your Media Shuttle Send, Share, or Submit portals, or operations performed on files and folders in Share portals.

A transfer package can contain a number of files and folders that are sent using Media Shuttle.

Portal event subscription webhooks are sent upon the successful completion of uploads, downloads and file operations. Webhooks include the event type, the transfer’s timestamp, and payload as a JSON object.

Payload Details

A transfer’s payload includes the Operation Details for the transfer and Portal Details of the portal used to do the transfer.

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

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.

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 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 are sent after the successful completion of a package upload and download, and include the event type, the transfer’s timestamp, and files included in the package.

Transfer Event Types

Portal events include:

  • package.upload.complete
  • package.upload.canceled
  • package.upload.failed
  • package.download.complete
  • package.download.canceled
  • package.download.failed

Example Webhook Responses

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.

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.

Event Types

Token events include:

  • package.upload.complete
  • package.download.complete
  • tokenRedeemed

Example Webhook Response

{
  "eventType": "package.upload.complete",
  "timestamp": "2018-03-02T19:20:50.52.000Z",
  "payload": {
    "tokenId": "98453210-ABCD-WXYZ-ABCD-127371111987",
    "grants": [
      "upload"
    ],
    "userEmail": "user@example.com",
    "packageId": "m42kqJGGOyGagudcFANQIR",
    "portalId": "12345678-ABCD-WXYZ-DCBA-12345c678987",
    "transferId": "35460d47-019b-4e06-8108-18343b235108"
  }
}

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.

Event Types

  • file.rename.complete
  • file.rename.failed
  • file.move.complete
  • file.move.failed
  • file.delete.complete
  • file.delete.failed
  • folder.creation.complete
  • folder.creation.failed

Note: Files and folders can be renamed, moved, and deleted. The isFolder attribute indicates whether the operation was performed on a file or folder.

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