Webhooks

Webhooks allow you to receive real-time notifications when events occur in your WalletWerk account. This enables you to keep your systems in sync without polling the API.

Setting Up Webhooks

1. Create a Webhook Endpoint

   • Log in to your dashboard
   • Navigate to Developer → Webhooks
   • Click Add Webhook
   • Enter your endpoint URL (must be HTTPS in production)
   • Select which events to subscribe to
   • Copy and securely store your signing secret
     You'll only see it once!

2. Verify Webhook Signatures

   All webhook payloads include a signature in the X-WalletWerk-Signature header. You must verify this signature to ensure the request is from WalletWerk.

   How it works:

   • WalletWerk sends the raw JSON body (as a string) and a signature header
   • You compute an HMAC-SHA256 hash of the raw JSON body using your secret
   • Compare your computed hash with the signature in the header
   • If they match, the webhook is authentic

   Important: You must use the raw JSON body (as received, before parsing), not the parsed JSON object. The signature is computed from the exact bytes of the request body.

   Node.jsPython

   const crypto = require('crypto');
   const express = require('express');
   const app = express();
   
   function verifySignature(rawBody, signature, secret) {
     // Compute HMAC-SHA256 of the raw body
     const expected = crypto
       .createHmac('sha256', secret)
       .update(rawBody)
       .digest('hex');
     
     // Compare signatures using constant-time comparison
     return crypto.timingSafeEqual(
       Buffer.from(signature),
       Buffer.from(expected)
     );
   }
   
   // IMPORTANT: Use express.raw() to get the raw body as a Buffer
   app.post('/webhooks/walletwerk', express.raw({ type: 'application/json' }), (req, res) => {
     const signature = req.headers['x-walletwerk-signature'];
     const rawBody = req.body.toString('utf-8'); // Convert Buffer to string
     
     // Verify signature BEFORE parsing JSON
     if (!verifySignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
       return res.status(401).send('Invalid signature');
     }
     
     // Now safe to parse JSON
     const event = JSON.parse(rawBody);
     // Process the event...
     res.status(200).send('OK');
   });
   

   from flask import Flask, request, jsonify
   import hmac
   import hashlib
   import os
   
   app = Flask(__name__)
   
   def verify_signature(raw_body, signature, secret):
       # Compute HMAC-SHA256 of the raw body
       expected = hmac.new(
           secret.encode('utf-8'),
           raw_body.encode('utf-8'),
           hashlib.sha256
       ).hexdigest()
       
       # Compare signatures using constant-time comparison
       return hmac.compare_digest(signature, expected)
   
   @app.route('/webhooks/walletwerk', methods=['POST'])
   def webhook_handler():
       signature = request.headers.get('X-WalletWerk-Signature')
       raw_body = request.get_data(as_text=True)  # Get raw body as string
       
       # Verify signature BEFORE parsing JSON
       if not verify_signature(raw_body, signature, os.environ['WEBHOOK_SECRET']):
           return jsonify({'error': 'Invalid signature'}), 401
       
       # Now safe to parse JSON
       event = request.get_json()
       # Process the event...
       return jsonify({'status': 'ok'}), 200
   

   Common Mistakes:

   • ❌ Parsing JSON before verifying the signature
   • ❌ Using req.body after JSON parsing (Express) or request.json (Flask) instead of raw body
   • ❌ Not using constant-time comparison (vulnerable to timing attacks)
   • ✅ Always verify the signature using the raw request body string

When We Send Events

WalletWerk sends webhook events when:

• A wallet card is created, updated, or changes status
• A recipient is added, invited, or updated
• A campaign is created or updated
• A user adds or removes a card from their wallet
• A card is revoked or expires

Event Types

Card Events

Recipient Events

Campaign Events

Event Payload

All webhook payloads follow this structure:

{
  "event": "card.active",
  "timestamp": "2025-12-09T10:30:00Z",
  "organization_id": 123,
  "data": {
    "card_id": "card_abc123",
    "recipient_id": "recipient_xyz789",
    "campaign_id": "campaign_def456",
    "provider": "apple",
    "old_status": "invited",
    "new_status": "active",
    "metadata": {}
  }
}

Status Fields in Webhook Payloads:

• Card events (card.*): old_status and new_status show wallet card status changes (active, removed, revoked, expired)
• Recipient events (recipient.*): old_status and new_status show recipient status changes (pending, created, invited, active, revoked, deleted)
• Campaign events (campaign.*): Status fields may not be present

Verify Signatures

Every webhook request includes these headers:

See the Setting Up Webhooks section above for signature verification code examples.

Retry Behavior and Disabling

Retry Logic

WalletWerk will retry failed deliveries with exponential backoff:

• First retry: 1 minute
• Second retry: 5 minutes
• Third retry: 15 minutes
• Fourth retry: 1 hour
• Maximum: 24 hours

Timeout

Webhook endpoints must respond within 30 seconds. If your endpoint doesn't respond within this time, WalletWerk will consider the delivery failed and retry.

Failure Handling

Idempotency

Use the X-WalletWerk-Delivery-ID header to ensure idempotent processing. Each webhook delivery has a unique ID that you can use to prevent duplicate processing:

// Store processed delivery IDs
const processedIds = new Set();

app.post('/webhooks/walletwerk', express.raw({ type: 'application/json' }), (req, res) => {
  const deliveryId = req.headers['x-walletwerk-delivery-id'];
  
  // Check if we've already processed this delivery
  if (processedIds.has(deliveryId)) {
    return res.status(200).send('OK'); // Already processed
  }
  
  // Process the event...
  processedIds.add(deliveryId);
  res.status(200).send('OK');
});

Testing Webhooks

You can test your webhook endpoint from the dashboard:

1. Navigate to Developer → Webhooks
2. Click the test button (send icon) next to your webhook
3. A test payload will be sent to your endpoint with event type webhook.test

The test payload follows the same format as regular webhook events, allowing you to verify your signature verification and event handling logic.