ShareFile API
  • Not Currently Logged In |
    Log In
  • ||
    Logout
  • arrow Getting Started
    • Quick Start Guide
    • OData Implementation
    • FAQ
    • Authentication
    • Postman
    • Storage Zones
  • Get an API Key
  • arrow API Entities
    • AccessControls
    • Accounts
    • Apps
    • AsyncOperations
    • Capabilities
    • ConnectorGroups
    • Devices
    • EncryptedEmails
    • FavoriteFolders
    • Favorites
    • FolderTemplates
    • Groups
    • Items
    • Metadata
    • Policies
    • Reports
    • Sessions
    • Shares
    • StorageCenters
    • Users
    • WebhookClients
    • WebhookSubscriptions
    • Workflows
    • Zones
  • arrowWebhooks
    • Overview
    • Events
    • Payloads
    • Signature Keys
  • arrowHow-To Guides
    • Common Use Cases
    • Troubleshooting
  • arrowCode Samples
    • C#(.NET)
    • Command Line / CURL
    • PHP
    • Python
    • Ruby
    • VB(.NET)
  • arrowSDKs
    • PowerShell
    • .NET
    • JavaScript

Webhook Payloads

After you subscribe to an event via webhook subscriptions you will start recieving event notifications whenever the subscribed event occurs. The ShareFile platform will POST over HTTP the payload of the event to the URL you specified in your subscription. The ShareFile Platform expects a 2XX response back in 10 seconds to indicate a success. If we do not receive a successful response within that timeframe, we will consider it a failure. If we get back a non-successful status code, we will retry the attempt for the following responses:

  • 429 - Too Many Requests
  • 500 - Internal Server Error
  • 501 - Not Implemented
  • 502 - Bad Gateway
  • 503 - Service Unavailable
  • 504 - Gateway Timeout
  • Connection Timeout

ShareFile uses an exponential back-off strategy when retrying the callback to avoid overloading the destination server. Currently there is a Time-to-Live of 7 days on the event, and as such, retries may stop after that time span. Note that this is subject to change.

Example Payload

All callback payloads will have a set of standard fields to help you process the event. There are also fields that will be dynamic depending on the event that occurred.

Example:

In the example above, the fields other than Resource are all standard across events. The Resource field will change depending on the event type. The Resource field, will use a style similar to our V3 API Model of the Resource the event is about.

Webhook Signatures

ShareFile employs the use of signatures to prevent attacks against your callback endpoints. Once you set up a signature key, ShareFile will use that key to create a cryptographic digest of the webhook payload using HMAC SHA256. The value that gets computed will be returned in a header. Your application can then compute the same value and verify that ShareFile sent the message. This will also verify that the message has not been tampered with mid transit via a man in the middle attack. ShareFile also provides the opportunity to rotate your keys for further security by providing two signatures, allowing one to be changed at a time.


Generating and Rotating Signature Keys

For ShareFile to sign the webhook payloads, you must first generate signature keys for your application. Each OAuth client will have a set of two signature keys. This allows for key rotation. After logging in, click here to generate them. By clicking the Generate button next to each value, you will be setting a new key to be used.


In order to rotate keys, you will want to change only one of your keys at a time by clicking the Generate button either beside the Primary Signature Key value or the Secondary Signature Key value. Once you change it, your application will still accept payloads from Sharefile, since one of the signatures will be valid. You will then want to update your application with the new key and after some time all payloads will once again validate both signatures. After a suitable time, once you are sure there are no more notifications in flight with the old signature key, you can use the same steps to update the key that was not updated previously. ShareFile highly recommends updating your signature keys to ensure best security practices.


Verifying Payloads

After you have successfully generated a primary and secondary signature key, ShareFile will include three headers with the payload sent to your callback url. The first header is SF-WEBHOOK-TIMESTAMP. This header will include the time the payload was generated to be sent. You can use this header to verify that the payload was not overly delayed. We suggest not accepting payloads as valid that are over 15 minutes old. The other two headers are the digests of the payload, SF-WEBHOOK-SIGNATURE-PRIMARY and SF-WEBHOOK-SIGNATURE-SECONDARY. To verify the signatures in these headers you should take the following steps:

  1. Verify the value in SF-WEBHOOK-TIMESTAMP is no older than 15 minutes using UTC.
  2. Convert the payload UTF-8 text to an array of bytes.
  3. Convert the value in SF-WEBHOOK-TIMESTAMP as UTF-8 text to an array of bytes and append it to the end of the payload array.
  4. Utilizing HMAC SHA256, create digests for combined array of bytes, using each of your signature keys.
  5. Convert both digests to text using base64 encoding.
  6. Compare the two values you calculated to the values in each of the signature headers SF-WEBHOOK-SIGNATURE-PRIMARY and SF-WEBHOOK-SIGNATURE-SECONDARY. If either match, you can accept the payload as valid and non-tampered.

The following C# code provides an example of the verification: