Box.com integration: method and functional background

The Box.com integration handles digital signatures on orders via Box Sign. When an order reaches the “request signature” status, i-Reserve generates PDF documents from order templates, uploads them to Box and creates a Box Sign request that is sent to the customer. Once the customer signs, i-Reserve receives a webhook, downloads the signed documents and updates the order status.

Authentication

The integration uses a Box JWT app (server authentication with a service account), not an interactive OAuth login. i-Reserve signs a JWT (RS256) with the app credentials and exchanges it for an access token; the app operates at enterprise level. Required data: client id, client secret, public key id, private key (PEM), passphrase and enterprise id. Optionally you can act as a specific Box user via as user.

What happens at “request signature”

1. i-Reserve generates the PDF(s) from the configured order templates.
2. The PDFs are uploaded to Box (into a fixed i-Reserve folder the integration creates/reuses).
3. A Box Sign request is created with the customer as signer (and a recipient for the final copy). Fields can be pre-filled (prefill) with customer/company data.
4. The request gets an external_id in the format ord_{order_id}:int_{integration_id} so the webhook can find the right order later; the sign-request id is stored in an order field.

Webhook back from Box

During setup the integration registers a webhook on the Box folder for the events SIGN_REQUEST.COMPLETED, SIGN_REQUEST.DECLINED and SIGN_REQUEST.EXPIRED. Box sends notifications to the i-Reserve endpoint; these are verified with an HMAC-SHA256 signature. i-Reserve translates the event into an order status (signed / declined / expired), downloads the signed documents + the signing log and stores them as order documents.

Limitations

• Works at order level (not on individual bookings) and is focused on the Box Sign process.
• JWT service account only; no interactive per-customer login.
• Without selected order templates no sign request is created (silent no-op).
• The external_id format and the configured order field for the sign-request id are essential for the webhook link.
• The private key must be pasted correctly as PEM; the webhook URL Box calls back must be publicly reachable.