Hanzo
PlatformCommerce

Webhooks

Real-time event notifications

Webhooks

Receive real-time notifications when events occur in your commerce account.

Configure Webhook

await commerce.webhooks.create({
  url: 'https://myapp.com/webhooks/commerce',
  events: [
    'checkout.completed',
    'subscription.created',
    'payment.succeeded',
    'payment.failed'
  ],
  secret: 'whsec_...'  // optional, auto-generated if omitted
})

Events

EventDescription
checkout.completedCheckout finished successfully
order.createdNew order placed
payment.succeededPayment processed
payment.failedPayment declined or failed
subscription.createdNew subscription started
subscription.cancelledSubscription cancelled
subscription.updatedSubscription plan changed
invoice.paidInvoice payment received
invoice.failedInvoice payment failed
refund.createdRefund issued

Verify Signature

Always verify webhook signatures in production:

app.post('/webhooks/commerce', (req, res) => {
  const signature = req.headers['x-hanzo-signature']

  try {
    const event = commerce.webhooks.verify(
      req.rawBody,
      signature,
      process.env.WEBHOOK_SECRET
    )

    // Handle event
    switch (event.type) {
      case 'checkout.completed':
        await fulfillOrder(event.data)
        break
      case 'payment.failed':
        await notifyCustomer(event.data)
        break
    }

    res.status(200).json({ received: true })
  } catch (err) {
    res.status(400).json({ error: 'Invalid signature' })
  }
})

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

AttemptDelay
1Immediate
25 minutes
330 minutes
42 hours
524 hours

After 5 failed attempts, the webhook endpoint is disabled and an alert is sent.

How is this guide?

Last updated on

On this page