Join the first BoxWorks Hackathon for Good - customers, partners, and the developer community are welcome to participate in the 48 hour Hack to benefit The Nature Conservancy.

Learn more and register!

V2 Webhooks

V2 Webhooks

Flow

Webhook flow

When an event triggers a webhook for a file or a folder, it make a HTTP call to the address specified when the webhook was created. The payload of this call contains some request headers, and a JSON body.

Payload headers

The payload sent by a webhook has the following Box-specific headers.

HeaderDescription
BOX-DELIVERY-IDA unique ID assigned by Box that identifies the delivered webhook payload. When Box retries a webhook this ID will change, while the ID in the body of the payload remains the same.
BOX-DELIVERY-TIMESTAMPAn RFC-3339 timestamp that identifies the time that the payload was sent at.
BOX-SIGNATURE-PRIMARYA signature created using the primary signature key configured for this webhook.
BOX-SIGNATURE-SECONDARYA signature created using the secondary signature key configured for this webhook.
BOX-SIGNATURE-VERSIONValue is always 1.
BOX-SIGNATURE-ALGORITHMValue is always HmacSHA256 .

For example:

BOX-DELIVERY-ID:          673a081b-bb4b-4d45-b4f1-4131a29c1d07
BOX-DELIVERY-TIMESTAMP:   2016-07-11T10:10:33-07:00
BOX-SIGNATURE-PRIMARY:    isCeDp7mLR41/MjcSEFLag9bWmpJkgmN80Je4VIESdo=
BOX-SIGNATURE-SECONDARY:  1UbiiKS7/2o5vNIlyMh7e5QGCHq8lflWFgEF+YWBugI=
BOX-SIGNATURE-VERSION:    1
BOX-SIGNATURE-ALGORITHM:  HmacSHA256
USER-AGENT:               Box-WH-Client/0.1

We recommend setting up and verifying signatures of the webhook payloads.

HTTP header names are case insensitive and your client should ideally convert all header names to a standardized lowercase or uppercase format before trying to determine the value of a header.

Payload body

The body of a webhook payload is a JSON object that describes the file or folder (target) that triggered the webhook, as well as the event that has been triggered.

FieldDescription
typeValue is always webhook_event.
idA unique ID assigned by Box that identifies the event. When Box retries a webhook this ID will not change, while the ID in the header changes between calls.
created_atThe time/date that the event was triggered at.
triggerThe name of the event that triggered the event, for example FILE.UPLOADED.
webhookThe webhook ID for which this event triggered.
created_byThe user that triggered this event.
sourceThe item that triggered this event, for example the file that was uploaded to the target folder

For example:

{
  "type": "webhook_event",
  "id": "eb0c4e06-751f-442c-86f8-fd5bb404dbec",
  "created_at": "2016-07-11T10:10:32-07:00",
  "trigger": "FILE.UPLOADED",
  "webhook": {
    "id": "53",
    "type": "webhook"
  },
  "created_by": {
    "type": "user",
    "id": "226067247",
    "name": "John Q. Developer",
    "login": "johnq@dev.name"
  },
  "source": {
    "id": "73835521473",
    "type": "file",
    "file_version": {
      "type": "file_version",
      "id": "78096737033",
      "sha1": "2c61623e86bee78e6ab444af456bccc7a1164095"
    },
    "sequence_id": "0",
    "etag": "0",
    "sha1": "2c61623e86bee78e6ab444af456bccc7a1164095",
    "name": "Test-Image-3.png",
    "description": "",
    "size": 26458,
    "path_collection": {
      "total_count": 4,
      "entries": [
        {
          "type": "folder",
          "id": "0",
          "sequence_id": null,
          "etag": null,
          "name": "All Files"
        },
        {
          "type": "folder",
          "id": "2614853901",
          "sequence_id": "4",
          "etag": "4",
          "name": "Testing"
        },
        {
          "type": "folder",
          "id": "8290186265",
          "sequence_id": "0",
          "etag": "0",
          "name": "Webhooks Base"
        },
        {
          "type": "folder",
          "id": "8290188973",
          "sequence_id": "0",
          "etag": "0",
          "name": "Webhooks"
        }
      ]
    },
    "created_at": "2016-07-11T10:10:32-07:00",
    "modified_at": "2016-07-11T10:10:32-07:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2016-06-08T11:14:04-07:00",
    "content_modified_at": "2016-06-08T11:14:04-07:00",
    "created_by": {
      "type": "user",
      "id": "226067247",
      "name": "John Q. Developer",
      "login": "johnq@dev.name"
    },
    "modified_by": {
      "type": "user",
      "id": "226067247",
      "name": "John Q. Developer",
      "login": "johnq@dev.name"
    },
    "owned_by": {
      "type": "user",
      "id": "226067247",
      "name": "John Q. Developer",
      "login": "johnq@dev.name"
    },
    "shared_link": null,
    "parent": {
      "type": "folder",
      "id": "8290188973",
      "sequence_id": "0",
      "etag": "0",
      "name": "Webhooks"
    },
    "item_status": "active"
  },
  "additional_info": []
}

Retries

Delivery of a webhook payload fails when Box does not receive a response with a HTTP status code in the 200 to 299 range within 30 seconds of sending the payload.

When delivery of a webhook fails Box will resend it up to 10 times. The initial retry will take place 5 minutes after the failure. From there, an exponential back-off strategy is used to avoid overloading the destination server. By using exponential back- off, Box will wait an increasingly longer time for every retry.

Box will retry webhook deliveries up to 10 times. This number could be subject to change.