Webhooks Guide

Getting Started

1. Create a Webhook: Register a webhook by providing your endpoint URL and selecting which events you want to receive
2. Store Your Secret: When you create a webhook, you'll receive a secret key. Save this securely - you'll need it to verify incoming requests
3. Receive Events: When subscribed events occur, we'll send HTTP POST requests to your endpoint with event data
4. Verify & Process: Always verify the webhook signature before processing events to ensure they're authentic

Checkout Events

• checkout.created - Fired when a new checkout is created
• checkout.updated - Fired when a checkout is updated
• checkout.completed - Fired when a checkout is completed
• checkout.cancelled - Fired when a checkout is cancelled

Customer Events

• customer.created - Fired when a new customer is created
• customer.updated - Fired when customer information is updated
• customer.credit_check_completed - Fired when a customer credit check completes

Product Events

• product.created - Fired when a new product is created
• product.updated - Fired when product information is updated
• product.deleted - Fired when a product is deleted

Lease Events

• lease.started - Fired when a lease begins
• lease.ended - Fired when a lease ends

Payment Events

• payment.received - Fired when a payment is received

Webhook Headers

Every webhook request includes the following headers:

• X-Webhook-Signature - HMAC-SHA256 signature in format sha256=hex_signature
• X-Webhook-Timestamp - Unix timestamp when the request was signed
• X-Webhook-Event-Type - The event type that triggered this webhook
• X-Webhook-Event-ID - Unique identifier for this event occurrence

Signature Verification

The signature is computed as an HMAC-SHA256 hash of the timestamp and request body, using your webhook secret. The format is: HMAC-SHA256(timestamp + "." + body, secret)

To verify a webhook request:

1. Extract the X-Webhook-Signature header (remove the sha256= prefix)
2. Extract the X-Webhook-Timestamp header
3. Reconstruct the signed payload: timestamp + "." + request_body
4. Compute the expected signature using HMAC-SHA256 with your webhook secret
5. Compare the signatures using constant-time comparison to prevent timing attacks
6. Optionally check the timestamp to prevent replay attacks (recommended: reject requests older than 5 minutes)

Example: Verify Signature (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret, timestamp) {
  // Reconstruct the signed payload
  const signedPayload = `${timestamp}.${payload}`;
  
  // Compute the expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  // Extract the signature from the header (format: sha256=hex_signature)
  const receivedSignature = signature.replace('sha256=', '');
  
  // Compare signatures using constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  );
}

// Example usage in Express.js
app.post('/webhooks/sweetspot', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const eventType = req.headers['x-webhook-event-type'];
  const eventId = req.headers['x-webhook-event-id'];
  
  const webhookSecret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, webhookSecret, timestamp)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Check timestamp to prevent replay attacks (optional)
  const currentTime = Math.floor(Date.now() / 1000);
  const requestTime = parseInt(timestamp);
  if (Math.abs(currentTime - requestTime) > 300) { // 5 minutes tolerance
    return res.status(401).send('Request timestamp too old');
  }
  
  const event = JSON.parse(req.body);
  
  // Process the webhook event
  console.log('Received event:', eventType, eventId);
  
  res.status(200).send('OK');
});