Bamboo Card
Open in PostmanGo to Client Portal
HomeWebhooks

This page covers Bamboo's Svix-based webhook system for event-driven delivery and signature verification. If you need to configure the Notification URL callback endpoint, see the Notification API reference.

Webhooks

Receive near real-time notifications whenever there are updates to your catalog or orders. Eliminate the need to continuously poll the API to track changes in product status, stock, pricing, or order completions.

Triggered when changes happen to
  • Product availability or status
  • Product available stock
  • Product price or denomination (exchange rate changes excluded)
  • Order completed

Near Real-Time

Get notified instantly when products or orders change — no need to continuously poll the API.

Secure by Default

Every request is signed via Svix. Verify signatures with your Webhook Secret before processing.

Built-In Retries

Bamboo automatically retries failed deliveries. Your endpoint only needs to return HTTP 2xx.

Selective Events

Subscribe only to the events you need — product updates, order completions, or both.

Getting Started

Set up your webhook endpoint in the Bamboo Client Portal in five steps.

1

Navigate to Webhooks

In the Bamboo Client Portal, go to Sidebar → Webhooks.

2

Subscribe

Click "Subscribe to Bamboo Webhooks" to activate webhooks for your account. Done once per account.

3

Add Endpoint

Click "+ Add Endpoint", enter your HTTPS URL, and select the event types you want to receive.

4

Save the Secret

Copy or download the generated Webhook Secret immediately — it is shown only once and cannot be retrieved later.

5

Test & Configure

Send a test message from Webhooks → Test Messages to verify delivery, then configure stock notification settings.

Webhook Secret

After adding an endpoint, Bamboo generates a Webhook Secret. This secret is used to verify that incoming requests genuinely originated from Bamboo.

Save it immediately — shown only once

The secret cannot be retrieved after the dialog is closed. Copy or download it before clicking Done. If you lose it, go to Webhooks → Endpoints → Rotate Secret. The old secret remains valid for 24 hours so you can migrate without downtime.

Event Types

Select one or both event types when configuring an endpoint.

productupdated.v1Product changes

Triggered when product details such as pricing, face values, availability, or stock are modified. Payload includes both the old and new state of each changed product.

json
{
  "products": [
    {
      "id": 114111,
      "oldState": {
        "name": "iTunes USA eGift voucher",
        "status": "Available",
        "minFaceValue": 50,
        "maxFaceValue": 100,
        "quantity": 10,
        "price": { "min": 50, "max": 100, "currencyCode": "USD" },
        "modifiedDate": "2022-08-22T09:06:29.6783345"
      },
      "newState": {
        "name": "iTunes USA eGift voucher",
        "status": "Available",
        "minFaceValue": 100,
        "maxFaceValue": 100,
        "quantity": null,
        "price": { "min": 100, "max": 100, "currencyCode": "USD" },
        "modifiedDate": "2022-08-22T09:06:29.6783345"
      }
    }
  ],
  "timestamp": "2026-04-01T05:17:53.6491931Z"
}
ordercompleted.v1Order fulfilled

Triggered when an order reaches a final completed state. Use this to trigger downstream fulfillment, reconciliation, or customer notification workflows.

json
{
  "orderId": 100123,
  "status": "succeeded",
  "totalCards": 5,
  "createdOn": "2026-04-01T08:00:00+00:00",
  "completedOn": "2026-04-01T08:05:00+00:00",
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Signature Verification

Bamboo uses Svix for webhook delivery. Every request includes three headers that you must validate using your Webhook Secret.

svix-idsvix-timestampsvix-signature
Node.js — Svix verification
import { Webhook } from "svix";

const webhook = new Webhook("YOUR_WEBHOOK_SECRET");

export default async function handler(req, res) {
  const payload = JSON.stringify(req.body);

  try {
    const evt = webhook.verify(payload, {
      "svix-id": req.headers["svix-id"],
      "svix-timestamp": req.headers["svix-timestamp"],
      "svix-signature": req.headers["svix-signature"],
    });

    // Process evt here...
    res.status(200).send("OK");
  } catch (err) {
    res.status(400).send("Invalid signature");
  }
}

Stock Notification Settings

Control how frequently stock-related webhook events are sent. Go to Webhooks → Settings → Edit to configure.

Stock Notification Interval

The minimum time (in minutes) between consecutive stock quantity notifications. Set to 0 to receive updates immediately.

Only quantity updates are throttled — price, status, name, and face value changes are always sent immediately.

Low Stock Threshold

When available stock falls below this item count, a webhook is sent immediately regardless of the notification interval.

Useful for triggering urgent restocking alerts without waiting for the next scheduled interval.

Delivery Behavior

If your endpoint returns a non-2xx status, Bamboo automatically retries delivery. Price, status, name, and face value changes are always sent immediately regardless of interval settings.

Price / Name / Status / Face ValueSent immediately
Stock quantity updateBased on notification interval
Stock below low thresholdSent immediately
Order completedSent immediately
Endpoint returns non-2xxAuto-retried

Best Practices

  • Always verify webhook signatures using the Svix library
  • Return HTTP 200 immediately — do heavy processing asynchronously
  • Use idempotent handlers to safely handle duplicate deliveries
  • Log every delivery for debugging and audit purposes
  • Rotate your Webhook Secret periodically

Need help setting up webhooks?

Start with Troubleshooting or explore the API notification endpoint.

Notification API Troubleshooting