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-Idempotency-Key: <stable_notification_key>
X-BasaltSurge-Timestamp: <unix_ms>
User-Agent: BasaltSurge-Webhook/1.0

Body (Success / Paid)#

json
{
  "event": "receipt.status_updated",
  "idempotencyKey": "receipt-status:order_abc:paid:0xabc123...",
  "receiptId": "order_abc",
  "status": "paid",
  "previousStatus": "pending",
  "transactionHash": "0xabc123...",
  "buyerWallet": "0x1234...abcd",
  "merchantWallet": "0x5678...efgh",
  "totalUsd": 25.00,
  "customerTotalUsd": 26.25,
  "stripeSourceAmountUsd": 25.34,
  "token": "USDC",
  "timestamp": 1713200000000,
  "brandKey": "myshop",
  "stripeSessionId": "cos_8a7a48c2-6bae-4b08-9d36-35670b42dc8d",
  "isStripeSessionUnique": true,
  "transactionId": "TX-99882211",
  "metadata": {
    "orderRef": "ERP-PO-774",
    "customerTier": "vip"
  }
}

Body (Failed / Declined)#

json
{
  "event": "receipt.status_updated",
  "receiptId": "order_abc",
  "status": "failed",
  "previousStatus": "pending",
  "failureCode": "PORTAL_PAY_INSUFFICIENT_FUNDS",
  "failureCategory": "card_decline",
  "failureReason": "The payment method was declined due to insufficient available funds.",
  "failureAction": "Ask the customer to retry with another card or use an alternate payment method.",
  "merchantWallet": "0x5678...efgh",
  "totalUsd": 25.00,
  "token": "USDC",
  "timestamp": 1713200000000,
  "brandKey": "myshop",
  "stripeSessionId": "cos_8a7a48c2-6bae-4b08-9d36-35670b42dc8d",
  "isStripeSessionUnique": true
}

Payload Fields#

event

receipt.status_updated

idempotencyKey

X-BasaltSurge-Idempotency-Key

receiptId

status

paid

failed

previousStatus

failureCode

PORTAL_PAY_INSUFFICIENT_FUNDS

PORTAL_KYC_DOC_UNREADABLE

failureCategory

card_decline

compliance

limits

blockchain

session

system

failureReason

failureAction

providerErrorCode

failureCode

providerRequestId

req_...

transactionHash

buyerWallet

merchantWallet

totalUsd

customerTotalUsd

stripeSourceAmountUsd

source_amount

stripeSessionId

isStripeSessionUnique

true

stripeSessionId

false

transactionId

metadata

timestamp

Status Values#

status

pending

paid

paid - ach pending

ach_pending

reconciled

failed

rejected

abandoned

refund_requested

refunded

link_opened

checkout_initialized

onramp_*

error

checkout_success

paid

null

GET /api/receipts/status

Blocked transaction example#

json
{
  "event": "receipt.status_updated",
  "receiptId": "order_abc",
  "status": "failed",
  "previousStatus": "pending",
  "failureCode": "PORTAL_PAY_TRANSACTION_BLOCKED",
  "failureCategory": "compliance",
  "failureReason": "This transaction has been blocked.",
  "failureAction": "This purchase cannot continue. Contact support; do not submit another payment.",
  "providerErrorCode": "crypto_onramp_transaction_blocked",
  "providerRequestId": "req_Example123",
  "merchantWallet": "0x5678...efgh",
  "stripeSessionId": "cos_example",
  "totalUsd": 61.94,
  "timestamp": 1713200000000
}

null

Signature Verification#

Ocp-Apim-Subscription-Key

x-api-key

Verification Example (Node.js)#

javascript
import crypto from 'crypto';
import express from 'express';

const app = express();

function verifyWebhookSignature(body, signature, secret) {
  if (typeof signature !== 'string' || !/^sha256=[a-f0-9]{64}$/i.test(signature)) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  
  const received = signature.slice('sha256='.length);
  
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  );
}

// Register this route BEFORE a global express.json() middleware.
// Signature verification requires the exact received bytes.
app.post('/api/basaltsurge-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['X-BasaltSurge-Signature'];
  const rawBody = 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, idempotencyKey } = JSON.parse(rawBody.toString('utf8'));
  
  // Persist/check idempotencyKey with your order update in one DB transaction.
  // A delivery ID identifies a delivery cycle, not all later retries.
  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: Persist
  markup

  X-BasaltSurge-Idempotency-Key

  (or the body
  markup

  idempotencyKey

  ) with your order update. The key is stable across retries of the same receipt/status/transaction notification.
  markup

  X-BasaltSurge-Delivery

  identifies a delivery cycle and can change when a worker retries it later.

GET /api/receipts/status

X-{Brand}-*

X-BasaltSurge-*

2xx

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