Box Sign webhooks

Signature requests are asynchronous. Signers can complete, decline, or ignore a request at any time, including outside your app. A webhook on the destination folder notifies your app when those events happen. Set the listener on a folder or a document. The usual approach is the folder where you create signature requests, so one webhook covers every request in that folder. Examples of events you can listen for:

SIGN_REQUEST.COMPLETED, when a signature request is completed
SIGN_REQUEST.DECLINED, when a signature request is declined
SIGN_REQUEST.EXPIRED, when a signature request expires
SIGN_REQUEST.SIGNER_EMAIL_BOUNCED, when a signer’s email is bounced
SIGN_REQUEST.SIGNER_SIGNED, when a particular signer signs the request
SIGN_REQUEST.SIGNATURE_REQUESTED, when a signature is requested from a signer
SIGN_REQUEST.ERROR_FINALIZING, when the signature request could not be processed

For the full list of triggers, see webhook triggers.

Create a Sign webhook

Sign webhooks use the standard Box webhooks infrastructure. To receive Box Sign events, call the create webhook endpoint. Set the target to the folder where you create signature requests, and list the SIGN_REQUEST.* triggers you want to receive.

This API requires the application to have the Manage Webhooks scope enabled.

curl -i -X POST "https://api.box.com/2.0/webhooks" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "target": {
         "id": "12345",
         "type": "folder"
       },
       "address": "https://example.com/sign-webhooks",
       "triggers": [
         "SIGN_REQUEST.COMPLETED",
         "SIGN_REQUEST.DECLINED",
         "SIGN_REQUEST.EXPIRED"
       ]
     }'

For more ways to create webhooks, including the Developer Console and SDK examples, see Create webhooks (v2).

Receive Sign event notifications

When a Box Sign event occurs, Box sends an HTTP POST request to the address you configured. The payload includes the trigger and Sign-specific additional_info, such as the sign request ID and signer emails. It can also include a source file for the signature request. For example, when a signature request is completed, Box sends a payload similar to the following:

{
  "type": "webhook_event",
  "id": "eb0c4e06-751f-442c-86f8-fd5bb404dbec",
  "created_at": "2024-05-22T08:28:56-07:00",
  "trigger": "SIGN_REQUEST.COMPLETED",
  "webhook": {
    "id": "53",
    "type": "webhook"
  },
  "created_by": {
    "type": "user",
    "id": "226067247",
    "name": "John Q. Developer",
    "login": "johnq@dev.name"
  },
  "source": {
    "id": "73835521473",
    "type": "file",
    "name": "Contract.pdf",
    "item_status": "active"
  },
  "additional_info": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "signer_emails": [
      "johnq@dev.name",
      "signer@example.com"
    ],
    "external_id": ""
  }
}

Your endpoint must respond with an HTTP status code in the 200 to 299 range within 30 seconds to acknowledge the notification. For the full payload format and delivery details, see webhooks (v2). To verify that a notification was sent by Box, see Verify Box webhook signatures.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Create a Sign webhook

Receive Sign event notifications

​Sign-related events

​Create a Sign webhook

​Receive Sign event notifications

Sign-related events

Create a Sign webhook

Receive Sign event notifications