Webhooks

Webhooks let you subscribe to events in Beach Depository so your systems can react in real time — no polling required. When an event occurs (for example, an item is vaulted or an outbound shipment is delivered), Beach Depository delivers a signed HTTP POST to your registered URL via Svix.

How it works

Event occurs (e.g. inventory vaulted)
└── Beach Depository sends the event to Svix
    ├── Svix signs the payload
    ├── POSTs to your registered URL(s)
    ├── Retries on failure with exponential backoff
    └── Logs delivery status in the App Portal

Register a webhook endpoint via the API
Select which event types to subscribe to
Store the signing secret securely — it is only shown once at creation
Beach Depository delivers to your URL whenever a subscribed event fires

Inbound journey

The main inbound custody flow and the webhooks you receive:

Customer step	Event	Status signal
Customer ships	`inbound_shipment.status_changed`	`toStatus`: `pending` or `in_transit`
Arrives at vault	`inbound_shipment.status_changed`	`toStatus`: `received`
Getting checked in	`inbound_shipment.status_changed`	`toStatus`: `inspecting`
Checked in	`inbound_shipment.status_changed`	`toStatus`: `accepted`, `partially_accepted`, or `rejected`
Vaulted	`inventory.vaulted` and `inventory.status_changed`	`status` / `toStatus`: `in_vault`

Between checked in and vaulted, items may be held internally before shelving. That intermediate state is not sent on webhooks. The first inventory webhook is vaulted.

What you will not receive

Floor-only inbound gate: pending_approval
Pre-vault inventory state: pending_shelve
Vault bin locations (binId / facility topology)
Outbound floor packing statuses: packing, inspecting, pending_approval on outbound shipments
Staff IDs, workstations, or check-in / shelving session identifiers

Creating a webhook

Via the API

Create endpoints with the API so URL rules (HTTPS + public hostname) are enforced:

curl -X POST https://api.beachdepository.com/v1/webhooks \
  -H "Authorization: Bearer pv_live_your_api_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory Notifications",
    "url": "https://example.com/webhooks/purevault",
    "events": ["inventory.vaulted", "outbound_shipment.status_changed"]
  }'

Response:

{
  "data": {
    "id": "ep_abc123",
    "signingSecret": "whsec_d4d6eb900e291d584a235aeebff1aabe..."
  }
}

The signing secret is only returned once at creation time. Store it securely — you will not be able to retrieve it again from the create response (you can rotate it in Settings > Webhooks).

Via the dashboard

Navigate to Settings > Webhooks to inspect deliveries, replay messages, and rotate signing secrets. Endpoint create/edit (including URL changes) is API-only so public-hostname URL validation cannot be bypassed.

Event types

Event	Description
`inventory.vaulted`	An inventory item was vaulted and is available in vault
`inventory.status_changed`	An inventory item’s public status changed
`inventory.valuation_changed`	A new valuation was recorded for a product
`inbound_shipment.status_changed`	An inbound shipment’s status changed
`outbound_shipment.status_changed`	An outbound shipment’s public status changed
`outbound_request.status_changed`	An outbound request’s status changed
`transfer.status_changed`	A transfer’s public status changed
`transfer.completed`	A transfer was completed
`fbo_account.created`	A new FBO account was created
`fbo_account.updated`	An FBO account was updated
`statement.generated`	A holding statement was generated

Payload format

All webhook payloads follow the same structure:

{
  "event": "inventory.vaulted",
  "timestamp": 1709654321,
  "data": {
    "id": "jd7abc123xyz",
    "organizationId": "k57orgxyz",
    "fboAccountId": "m97fbo456",
    "status": "in_vault"
  }
}

event — one of the event types listed above
timestamp — Unix seconds when Beach Depository queued the delivery
data — event-specific fields; always includes id and organizationId
Document IDs are opaque Convex IDs (not prefixed strings like ship_…)

Status values

Whenever a payload includes status, fromStatus, or toStatus, the value is one of the sets below. fromStatus is omitted when the previous status was internal-only (not customer-visible).

Inventory (`status` / `fromStatus` / `toStatus`)

Inbound shipment (`fromStatus` / `toStatus`)

Outbound request (`fromStatus` / `toStatus`)

Outbound shipment (`fromStatus` / `toStatus`)

approved | picked_up_by_carrier | shipped | delivered

Transfer (`fromStatus` / `toStatus`)

Event payloads

`inventory.vaulted`

Fired once when an item first becomes available in vault (in_vault).

Field	Type	Description
`id`	string	Inventory item ID
`organizationId`	string	Owning organization ID
`fboAccountId`	string	FBO account ID
`productId`	string	optional — Product ID
`inboundShipmentId`	string	optional — Source inbound shipment ID
`status`	string	Always `in_vault`

`inventory.status_changed`

Field	Type	Description
`id`	string	Inventory item ID
`organizationId`	string	Owning organization ID
`fboAccountId`	string	FBO account ID
`productId`	string	optional
`inboundShipmentId`	string	optional
`fromStatus`	string	optional — previous public status
`toStatus`	string	New public status (see inventory values above)

`inventory.valuation_changed`

Field	Type	Description
`id`	string	Valuation record ID
`organizationId`	string	Organization that holds inventory for this product
`productId`	string	Product ID
`priceCents`	string	New price in cents (string for bigint safety)
`currency`	string	Currency code
`valuedAt`	number	Unix ms when the valuation was recorded

`inbound_shipment.status_changed`

Field	Type	Description
`id`	string	Inbound shipment ID
`organizationId`	string	Organization ID
`fboAccountId`	string	FBO account ID
`fromStatus`	string	optional — previous public status
`toStatus`	string	New status (see inbound values above)

`outbound_request.status_changed`

Field	Type	Description
`id`	string	Outbound request ID
`organizationId`	string	Organization ID
`fboAccountId`	string	FBO account ID
`fromStatus`	string	optional — previous public status
`toStatus`	string	New status (see outbound request values above)

Emitted on create (toStatus: "pending"), approve, deny, cancel, fulfilling, and fulfilled.

`outbound_shipment.status_changed`

Field	Type	Description
`id`	string	Outbound shipment ID
`organizationId`	string	Organization ID
`fboAccountId`	string	FBO account ID
`fromStatus`	string	optional — previous public status
`toStatus`	string	New status (see outbound shipment values above)
`deliveredAt`	number	optional — Unix ms when `toStatus` is `delivered`

Filter on toStatus: "delivered" for delivery notifications (there is no separate delivered event).

`transfer.status_changed`

Field	Type	Description
`id`	string	Transfer batch ID
`organizationId`	string	Organization ID
`fromFboAccountId`	string	Source FBO account ID
`toFboAccountId`	string	Destination FBO account ID
`fromStatus`	string	optional — previous public status
`toStatus`	string	New status (see transfer values above)
`items`	array	Line items: `{ inventoryItemId, reason }` (`request`, `trade`, `rebalance`)

`transfer.completed`

Field	Type	Description
`id`	string	Transfer batch ID
`organizationId`	string	Organization ID
`fromFboAccountId`	string	Source FBO account ID
`toFboAccountId`	string	Destination FBO account ID
`completedAt`	number	Unix ms completion time

`fbo_account.created`

Field	Type	Description
`id`	string	FBO account ID
`organizationId`	string	Organization ID
`email`	string	Account email
`firstName`	string	First name
`lastName`	string	Last name

`fbo_account.updated`

Field	Type	Description
`id`	string	FBO account ID
`organizationId`	string	Organization ID
`changedFields`	string[]	Names of fields that changed (values are not included)

`statement.generated`

Field	Type	Description
`id`	string	Statement ID
`organizationId`	string	Organization ID
`fboAccountId`	string	optional — Present for FBO statements
`statementType`	string	`org` or `fbo`
`statementDate`	string	Statement date (`YYYY-MM-DD`)
`totalItemCount`	number	Items included
`totalInsuredValueCents`	string	Total insured value in cents
`totalMarketValueCents`	string	Total market value in cents

Signature verification

Every webhook request includes Svix signature headers for verifying authenticity:

Header	Description
`svix-id`	Unique message ID (use for idempotency)
`svix-timestamp`	Unix timestamp when the message was signed
`svix-signature`	Space-separated list of signatures (`v1,...`)

Verifying in Node.js

import { Webhook } from "svix"

const secret = process.env.WEBHOOK_SECRET

// In your webhook handler — use the raw body string
app.post("/webhooks/purevault", (req, res) => {
  const payload = req.rawBody // raw request body as string
  const headers = {
    "svix-id": req.headers["svix-id"],
    "svix-timestamp": req.headers["svix-timestamp"],
    "svix-signature": req.headers["svix-signature"],
  }

  const wh = new Webhook(secret)
  let msg
  try {
    msg = wh.verify(payload, headers)
  } catch {
    return res.status(400).send("Invalid signature")
  }

  const { event, data } = msg
  console.log(`Received ${event}:`, data)

  res.status(200).send("OK")
})

Verifying in Python

from svix.webhooks import Webhook, WebhookVerificationError

secret = os.environ["WEBHOOK_SECRET"]

def handle_webhook(payload: bytes, headers: dict):
    wh = Webhook(secret)
    try:
        msg = wh.verify(payload, headers)
    except WebhookVerificationError:
        return False
    # Process msg["event"] / msg["data"]
    return True

See the Svix verifying payloads guide for more languages and framework examples.

Request headers

Each webhook delivery includes these headers:

Header	Description
`Content-Type`	`application/json`
`svix-id`	Unique message ID for idempotency
`svix-timestamp`	Signature timestamp
`svix-signature`	HMAC signature(s) for verification

Use svix-id to deduplicate events if your endpoint receives the same delivery more than once during retries.

Retry policy

Delivery retries are managed by Svix with automatic exponential backoff. Failed deliveries appear in Settings > Webhooks where you can inspect responses and replay messages after fixing your endpoint.

Best practices

Respond quickly

Return a 200 response as fast as possible. Process the event asynchronously (e.g., add it to a queue) rather than performing heavy work in the request handler.

Handle duplicates

Use the svix-id header to deduplicate. In rare cases, the same event may be delivered more than once during retries.

Verify signatures

Always verify the Svix signature headers before processing a webhook. This ensures the request came from Beach Depository and was not tampered with. Use the raw request body for verification.

HTTPS required

Webhook URLs must use https:// and a public DNS hostname. Bare IPs, private/loopback addresses, embedded credentials, and internal names (for example .local, .internal) are rejected. Create endpoints via the API so these rules are enforced.

Monitor deliveries

Check delivery history in Settings > Webhooks periodically. If your endpoint has been failing, fix the issue and replay missed messages from the portal.

Testing locally

Use a tool like webhook.site, Svix Play, or ngrok to receive webhooks during development:

# Start ngrok tunnel
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok-free.app/webhooks/purevault

Get Started

Core Concepts

Guides

How it works

Inbound journey

What you will not receive

Creating a webhook

Via the API

Via the dashboard

Event types

Payload format

Status values

Inventory (`status` / `fromStatus` / `toStatus`)

Inbound shipment (`fromStatus` / `toStatus`)

Outbound request (`fromStatus` / `toStatus`)

Outbound shipment (`fromStatus` / `toStatus`)

Transfer (`fromStatus` / `toStatus`)

Event payloads

`inventory.vaulted`

`inventory.status_changed`

`inventory.valuation_changed`

`inbound_shipment.status_changed`

`outbound_request.status_changed`

`outbound_shipment.status_changed`

`transfer.status_changed`

`transfer.completed`

`fbo_account.created`

`fbo_account.updated`

`statement.generated`

Signature verification

Verifying in Node.js

Verifying in Python

Request headers

Retry policy

Best practices

Testing locally

​How it works

​Inbound journey

​What you will not receive

​Creating a webhook

​Via the API

​Via the dashboard

​Event types

​Payload format

​Status values

​Inventory (status / fromStatus / toStatus)

​Inbound shipment (fromStatus / toStatus)

​Outbound request (fromStatus / toStatus)

​Outbound shipment (fromStatus / toStatus)

​Transfer (fromStatus / toStatus)

​Event payloads

​inventory.vaulted

​inventory.status_changed

​inventory.valuation_changed

​inbound_shipment.status_changed

​outbound_request.status_changed

​outbound_shipment.status_changed

​transfer.status_changed

​transfer.completed

​fbo_account.created

​fbo_account.updated

​statement.generated

​Signature verification

​Verifying in Node.js

​Verifying in Python

​Request headers

​Retry policy

​Best practices

​Testing locally

How it works

Inbound journey

What you will not receive

Creating a webhook

Via the API

Via the dashboard

Event types

Payload format

Status values

Inventory (`status` / `fromStatus` / `toStatus`)

Inbound shipment (`fromStatus` / `toStatus`)

Outbound request (`fromStatus` / `toStatus`)

Outbound shipment (`fromStatus` / `toStatus`)

Transfer (`fromStatus` / `toStatus`)

Event payloads

`inventory.vaulted`

`inventory.status_changed`

`inventory.valuation_changed`

`inbound_shipment.status_changed`

`outbound_request.status_changed`

`outbound_shipment.status_changed`

`transfer.status_changed`

`transfer.completed`

`fbo_account.created`

`fbo_account.updated`

`statement.generated`

Signature verification

Verifying in Node.js

Verifying in Python

Request headers

Retry policy

Best practices

Testing locally