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 (e.g., inventory received, shipment delivered), Beach Depository sends an HTTP POST to your registered URL with a signed JSON payload.

How it works

Event occurs (e.g. shipment delivered)
└── Beach Depository dispatches webhook
    ├── Signs payload with HMAC-SHA256
    ├── POSTs to your registered URL
    ├── Retries on failure (up to 3 attempts)
    └── Logs delivery status

Register a webhook endpoint in Settings > Webhooks or via the API
Select which event types to subscribe to
Store the signing secret securely — it is only shown once
Beach Depository POSTs to your URL whenever a subscribed event fires

Creating a webhook

Via the dashboard

Navigate to Settings > Webhooks and click Create Webhook. Enter a name, your endpoint URL, and select the events you want to receive. After creation, copy and store the signing secret.

Via the API

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.received", "outbound_shipment.delivered"]
  }'

Response:

{
  "data": {
    "id": "wh_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.

Event types

Event	Description
`inventory.received`	An inventory item was received into the vault
`inventory.status_changed`	An inventory item’s 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 status changed
`outbound_shipment.delivered`	An outbound shipment was delivered
`outbound_request.status_changed`	An outbound request’s status changed
`transfer.status_changed`	A transfer’s 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": "outbound_shipment.delivered",
  "timestamp": 1709654321,
  "data": {
    "id": "ship_abc123",
    "organizationId": "org_xyz",
    "fboAccountId": "fbo_456",
    "deliveredAt": 1709654321000
  }
}

The data object varies by event type but always includes id and organizationId.

Signature verification

Every webhook request includes an X-PureVault-Signature header for verifying authenticity:

X-PureVault-Signature: t=1709654321,v1=5257a869e7ecebeda32affa62cdca3fa51...

The signature is an HMAC-SHA256 hash of {timestamp}.{payload} using your signing secret.

Verifying in Node.js

import crypto from "crypto"

const MAX_TIMESTAMP_AGE_SECONDS = 300 // 5 minutes

function verifyWebhookSignature(payload, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=", 2)))

  // Reject stale timestamps to prevent replay attacks
  const timestamp = parseInt(parts.t, 10)
  const age = Math.floor(Date.now() / 1000) - timestamp
  if (isNaN(timestamp) || age > MAX_TIMESTAMP_AGE_SECONDS || age < 0) {
    return false
  }

  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${payload}`).digest("hex")

  // Constant-time comparison to prevent timing attacks
  const a = Buffer.from(expected, "hex")
  const b = Buffer.from(parts.v1 || "", "hex")
  if (a.length !== b.length) return false
  return crypto.timingSafeEqual(a, b)
}

// In your webhook handler
app.post("/webhooks/purevault", (req, res) => {
  const payload = JSON.stringify(req.body)
  const signature = req.headers["x-purevault-signature"]

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature")
  }

  // Process the event
  const { event, data } = req.body
  console.log(`Received ${event}:`, data)

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

Verifying in Python

import hmac
import hashlib
import time

MAX_TIMESTAMP_AGE_SECONDS = 300  # 5 minutes

def verify_webhook_signature(payload: bytes, signature_header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))

    # Reject stale timestamps to prevent replay attacks
    timestamp = int(parts.get("t", "0"))
    age = int(time.time()) - timestamp
    if age > MAX_TIMESTAMP_AGE_SECONDS or age < 0:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{parts['t']}.{payload.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(parts["v1"], expected)

Request headers

Each webhook delivery includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-PureVault-Signature`	HMAC-SHA256 signature for verification
`X-PureVault-Event-Id`	Unique event ID for idempotency
`X-PureVault-Event-Type`	The event type (e.g. `inventory.received`)
`User-Agent`	`PureVault-Webhooks/1.0`

Use X-PureVault-Event-Id to deduplicate events if your endpoint receives the same delivery more than once during retries.

Retry policy

If your endpoint returns a non-2xx status code or times out (10 seconds), Beach Depository retries with exponential backoff:

Attempt	Delay
1	Immediate
2	60 seconds
3	5 minutes

After 3 failed attempts, the delivery is marked as failed. You can view delivery history in the dashboard under Settings > Webhooks > View Deliveries.

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. Beach Depository times out after 10 seconds.

Handle duplicates

Use the X-PureVault-Event-Id header to deduplicate. In rare cases, the same event may be delivered more than once during retries.

Verify signatures

Always verify the X-PureVault-Signature header before processing a webhook. This ensures the request came from Beach Depository and was not tampered with.

HTTPS required

Webhook URLs must use https://. The API rejects http:// URLs and bare IP addresses. Endpoints must resolve to public hostnames — private, loopback, and link-local addresses are blocked.

Monitor deliveries

Check the delivery log in the dashboard periodically. If your endpoint has been failing, fix the issue and consider re-processing missed events via the API.

Testing locally

Use a tool like webhook.site 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

Creating a webhook

Via the dashboard

Via the API

Event types

Payload format

Signature verification

Verifying in Node.js

Verifying in Python

Request headers

Retry policy

Best practices

Testing locally

​How it works

​Creating a webhook

​Via the dashboard

​Via the API

​Event types

​Payload format

​Signature verification

​Verifying in Node.js

​Verifying in Python

​Request headers

​Retry policy

​Best practices

​Testing locally

How it works

Creating a webhook

Via the dashboard

Via the API

Event types

Payload format

Signature verification

Verifying in Node.js

Verifying in Python

Request headers

Retry policy

Best practices

Testing locally