Webhooks Patterns

Webhooks Patterns

The plugin itself doesn't subscribe to Box webhooks — there's no place to host a webhook receiver inside a Claude Code or Cowork plugin runtime. But if you self-host a server (anywhere with a public HTTPS endpoint), you can wire Box events to trigger box-memory workflows automatically.

Full reference at references/webhooks.md.

When to use webhooks

• You operate your own HTTPS-reachable server
• You want automatic actions on Box-side changes (file uploaded → auto-companion generated)
• You have IT / DevOps capacity to maintain the receiver + HMAC verification

If none of those apply, skip webhooks. The plugin works fine in pull-mode (user invokes skills or Claude does on demand).

Box webhook v2 basics

Box webhooks v2 (GA) let you subscribe to events on specific files or folders. When the event fires, Box POSTs the event payload to your address.

• 30+ trigger types: FILE.UPLOADED, FILE.COPIED, FILE.MOVED, FILE.DELETED, FILE.RENAMED, METADATA_INSTANCE.CREATED/UPDATED/DELETED, FOLDER.CREATED, COMMENT.CREATED, etc.
• Target = a file ID or folder ID (subscribe per-resource, not per-account)
• Up to 5 webhooks per resource, 1,000 per Box application
• HMAC-SHA256 signature verification via webhook primary/secondary key headers
• Retry: ~24 h with exponential backoff
• Address must be HTTPS and publicly reachable from Box's IP ranges

Recommended patterns for box-memory

Pattern 1: Auto-companion on file upload

Trigger: FILE.UPLOADED on the workspace's files/ folder.

Receiver flow:

1. Verify HMAC signature
2. Extract source.id, source.parent.id, source.name
3. If file is a supported binary (PDF / DOCX / image / CAD / Office), trigger companion generation
4. Your agent loop invokes /box-companion <file_id> — the plugin handles the rest (uses Box AI Extract on Business+, falls back to sparse on Personal)
5. Companion .md is written to Box; _index.json updated

Latency budget: webhook delivery (~seconds) + agent invocation (~seconds) + companion gen (~tens of seconds with AI). End-to-end typically <2 minutes.

Pattern 2: Auto-rebuild on manual Box edits

Trigger: METADATA_INSTANCE.UPDATED and METADATA_INSTANCE.DELETED on memory files.

Receiver flow:

1. Verify signature
2. Mark the affected folder "needs reindex" in your control plane
3. Throttle: aggregate over a 5-minute window
4. Agent loop invokes /box-index-rebuild --team=<affected> once per window

Pattern 3: Alert on companion staleness

Trigger: FILE.UPLOADED (new version of an existing binary).

Receiver flow:

1. Verify signature
2. Look up existing companion via _index.json.by_companion_for[<file_id>]
3. Compare binary's current sha1 to companion's stored sha1
4. If different → companion is stale. Either auto-regenerate via /box-companion or notify the user

HMAC verification sample (Python)

import hmac, hashlib

def verify_box_webhook(body_bytes, header_signature, primary_key, secondary_key):
    expected_primary = hmac.new(
        primary_key.encode('utf-8'), body_bytes, hashlib.sha256
    ).hexdigest()
    if hmac.compare_digest(expected_primary, header_signature):
        return True
    expected_secondary = hmac.new(
        secondary_key.encode('utf-8'), body_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_secondary, header_signature)

Box guidance: Webhooks v2 signatures.

Subscribing to a webhook

Use the Box MCP's create_webhook tool, or POST /2.0/webhooks via the SDK:

{
  "target": {"id": "<folder_id>", "type": "folder"},
  "address": "https://your-receiver.example.com/box-webhook",
  "triggers": ["FILE.UPLOADED", "FILE.COPIED"]
}

Why not Box Automate?

Box Automate (GA Apr 2026) is Box-hosted workflow automation. For "on upload → run AI on the file → write metadata" you can use Automate without hosting a receiver. The downside vs webhooks: Automate doesn't write companion markdown files (only metadata), so you lose the human-readable companion artifact and the hash-anchored review record.

Use Automate when: in-Box metadata is sufficient, no companion markdown needed. Use webhooks when: you want the full companion markdown artifact, or you need to coordinate with non-Box systems.

Air-gap incompatibility

Webhooks are incompatible with the on-prem (air-gapped) variant — they require a publicly reachable HTTPS endpoint, which violates the air-gap claim. Use webhooks only with the cloud plugin.

For event-driven on-prem behavior, use a periodic local FS scan (cron job runs /box-index-rebuild) or Box Drive's local change notifications (FSEvents / ReadDirectoryChangesW).

See also

• references/webhooks.md — full reference with all patterns
• Box webhooks v2 guide
• Box Automate — Box-hosted alternative