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.

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.

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. 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 package uploads and downloads, and include the event type, the transfer’s timestamp, and payload.

Payload Details

A transfer’s payload includes the Package 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.

Package Details

The payload includes details about the transfer 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.

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.

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 Response

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