Webhooks#

Receive push notifications when receipt status changes instead of polling.

Overview#

GET /api/receipts/status

When to Use Webhooks vs. Polling#

GET /api/receipts/status

Setup#

1. Configure Your Webhook Endpoint#

webhook_url

bash
curl -X POST "https://surge.basalthq.com/api/receipts" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $basaltsurge_API_KEY" \
  -d '{
    "id": "order_abc",
    "lineItems": [{ "label": "Widget", "priceUsd": 25.00 }],
    "totalUsd": 25.00,
    "webhook_url": "https://your-server.com/api/basaltsurge-webhook"
  }'

2. Requirements#

• HTTPS required in production (HTTP allowed in development)
• No localhost in production
• Must return
  markup

  2xx

  status within 5 seconds
• Must be idempotent (the same event may be delivered twice)

Webhook Payload#

POST

webhook_url

Headers#

markup
Content-Type: application/json
X-BasaltSurge-Signature: sha256=<hmac_hex>
X-BasaltSurge-Event: receipt.status_updated
X-BasaltSurge-Delivery: <uuid>
X-BasaltSurge-Timestamp: <unix_ms>
User-Agent: BasaltSurge-Webhook/1.0

Body#

json
{
  "event": "receipt.status_updated",
  "receiptId": "order_abc",
  "status": "paid",
  "previousStatus": "checkout_initialized",
  "transactionHash": "0xabc123...",
  "buyerWallet": "0x1234...abcd",
  "merchantWallet": "0x5678...efgh",
  "totalUsd": 25.00,
  "token": "USDC",
  "timestamp": 1713200000000,
  "brandKey": "myshop"
}

Status Values#

status

link_opened

buyer_logged_in

checkout_initialized

checkout_success

paid

reconciled

refund_requested

refunded

Signature Verification#

Ocp-Apim-Subscription-Key

x-api-key

Verification Example (Node.js)#

javascript
import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  
  const received = signature.replace('sha256=', '');
  
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  );
}

// Express.js handler
app.post('/api/basaltsurge-webhook', (req, res) => {
  const signature = req.headers['x-basaltsurge-signature'];
  const rawBody = JSON.stringify(req.body);
  
  // Use your same API key for verification
  if (!verifyWebhookSignature(rawBody, signature, process.env.basaltsurge_API_KEY)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const { event, receiptId, status, transactionHash } = req.body;
  
  // Process the event (ensure idempotency!)
  console.log(`Receipt ${receiptId} is now ${status}`);
  
  // Example: fulfill order when payment is confirmed
  if (status === 'paid' || status === 'reconciled') {
    fulfillOrder(receiptId, transactionHash);
  }
  
  res.status(200).json({ ok: true });
});

Verification Example (Python)#

python
import hmac, hashlib, json, os
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_signature(body: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body.encode(), hashlib.sha256
    ).hexdigest()
    received = signature.replace('sha256=', '')
    return hmac.compare_digest(expected, received)

@app.route('/api/basaltsurge-webhook', methods=['POST'])
def webhook():
    sig = request.headers.get('X-BasaltSurge-Signature', '')
    raw = request.get_data(as_text=True)
    
    # Use your same API key for verification
    if not verify_signature(raw, sig, os.environ['basaltsurge_API_KEY']):
        return jsonify(error='Invalid signature'), 401
    
    data = request.json
    receipt_id = data['receiptId']
    status = data['status']
    
    if status in ('paid', 'reconciled'):
        fulfill_order(receipt_id, data.get('transactionHash'))
    
    return jsonify(ok=True), 200

Delivery & Retry#

• Timeout: 5 seconds per attempt
• Retries: 1 automatic retry after 5 seconds if the first attempt fails
• Retry conditions: Non-2xx response, network error, or timeout
• Idempotency: Use the
  markup

  X-BasaltSurge-Delivery

  header as a unique delivery ID to deduplicate events

If both attempts fail, the event is logged but not retried further.

Platform / Partner Container Compatibility#

Webhook signing is container-stable: the API key used for signing is captured from the request header at receipt creation time and stored on the receipt document. This means:

• If a receipt is created on a partner container (e.g.,
  markup

  partner.basaltsurge.com

  ) using API key
  markup

  pk_abc...

  , that key is stored on the receipt.
• When Thirdweb or Stripe webhooks later fire on the platform container, the dispatch reads the signing secret from the receipt document — not from the platform's environment.
• Result: The developer always verifies webhooks with their same API key, regardless of which container processes the event.

Redirect URL (Stripe Only)#

redirect_url

redirect_url