Webhooks

Configure webhooks to receive real-time notifications about events in your Batch platform.

Overview

Webhooks allow your systems to react to events as they happen, enabling powerful integrations and automation.

What are Webhooks?

HTTP callbacks sent when events occur:

1. Event happens (e.g., order created)
2. Batch sends HTTP POST to your endpoint
3. Your system receives event data
4. Your system processes event
5. Your system responds with 200 OK

Use Cases

Order Processing

• New order → Send to fulfillment system
• Order shipped → Update CRM
• Refund processed → Notify accounting

Loyalty Events

• Points earned → Send congratulations email
• Tier upgraded → Unlock special access
• Reward redeemed → Update inventory

Customer Updates

• New customer → Add to email list
• Customer updated → Sync to CRM
• Account verified → Enable features

Product Events

• Product scanned → Analytics tracking
• Inventory low → Reorder alert
• New product → Update external catalog

Analytics

• All events → Data warehouse
• Purchases → Attribution tracking
• Engagement → Behavioral analysis

Available Events

Orders

• order.created
• order.updated
• order.paid
• order.shipped
• order.delivered
• order.cancelled
• order.refunded

Customers

• customer.created
• customer.updated
• customer.deleted
• customer.verified

Loyalty

• loyalty.points_earned
• loyalty.points_redeemed
• loyalty.tier_changed
• loyalty.reward_unlocked
• loyalty.campaign_completed

Products

• product.created
• product.updated
• product.scanned
• product.verified
• inventory.updated
• inventory.low_stock

Rewards

• reward.created
• reward.redeemed
• reward.expired

Setting Up Webhooks

Create Endpoint

1. Navigate to Settings > Webhooks
2. Click Add Endpoint
3. Configure:
   • URL: Your endpoint URL (HTTPS required)
   • Description: What this webhook does
   • Events: Select events to subscribe to
   • Active: Enable/disable

Secure Your Endpoint

HTTPS Required:

• Must use HTTPS (not HTTP)
• Valid SSL certificate
• No self-signed certificates

IP Whitelisting:

• Whitelist Batch IPs (if your firewall requires)

Webhook Signatures:

• Verify request authenticity
• Prevent tampering

Webhook Payload

Request Format

Headers:

POST /your-endpoint HTTP/1.1
Host: yourserver.com
Content-Type: application/json
X-Batch-Signature: sha256=abc123...
X-Batch-Event: order.created
X-Batch-Delivery-ID: uuid

Body:

{
  "event": "order.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "order-123",
    "customer_id": "customer-456",
    "total": 99.99,
    "items": [...],
    "status": "pending"
  }
}

Event-Specific Payloads

Order Created:

{
  "event": "order.created",
  "data": {
    "id": "ord_abc123",
    "number": "1001",
    "customer": {
      "id": "cus_xyz789",
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "items": [
      {
        "product_id": "prod_123",
        "quantity": 2,
        "price": 25.00
      }
    ],
    "total": 50.00,
    "status": "pending",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Points Earned:

{
  "event": "loyalty.points_earned",
  "data": {
    "customer_id": "cus_xyz789",
    "points": 50,
    "reason": "purchase",
    "reference_id": "ord_abc123",
    "balance": 550,
    "earned_at": "2025-01-15T10:30:00Z"
  }
}

Verifying Webhooks

Signature Verification

Verify requests came from Batch:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Process:

1. Get signing secret from Batch dashboard
2. Compute HMAC of raw request body
3. Compare with X-Batch-Signature header
4. Reject if mismatch

Handling Webhooks

Best Practices

Quick Response:

• Respond with 200 within 5 seconds
• Process asynchronously
• Queue for background processing

Idempotency:

• Use X-Batch-Delivery-ID to detect duplicates
• Store processed delivery IDs
• Skip duplicate events

Error Handling:

• Return 200 even if processing fails
• Log errors for investigation
• Retry failed processing separately

Example (Node.js):

app.post('/webhook', async (req, res) => {
  // 1. Verify signature
  if (!verifySignature(req.body, req.headers['x-batch-signature'], secret)) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Respond quickly
  res.status(200).send('OK');

  // 3. Process asynchronously
  queue.add('process-webhook', {
    event: req.body.event,
    data: req.body.data,
    deliveryId: req.headers['x-batch-delivery-id']
  });
});

Testing Webhooks

Test Events

Send test webhooks:

1. Go to webhook settings
2. Click Send Test Event
3. Select event type
4. View response

Local Testing

Test locally with tools:

ngrok:

ngrok http 3000
# Use ngrok URL as webhook endpoint

webhook.site:

• Temporary test endpoint
• View incoming requests
• Inspect payloads

Debugging

View webhook logs:

• Delivery attempts
• Response codes
• Response times
• Payload data
• Error messages

Retry Logic

Automatic Retries

If webhook fails:

1. First retry: After 1 minute
2. Second retry: After 5 minutes
3. Third retry: After 30 minutes
4. Fourth retry: After 2 hours
5. Fifth retry: After 6 hours

Failure Conditions

Retried when:

• No response
• Timeout (> 10 seconds)
• HTTP 5xx errors
• Network errors

Not Retried

No retry for:

• HTTP 2xx (success)
• HTTP 4xx (client error)
• Invalid endpoint

Manual Retry

Manually retry failed deliveries:

1. View webhook logs
2. Find failed delivery
3. Click Retry

Managing Webhooks

Edit Webhook

Modify existing webhook:

1. Click webhook
2. Update URL or events
3. Save changes

Disable Webhook

Temporarily stop deliveries:

• Toggle Active switch to off
• No deliveries sent
• Can re-enable anytime

Delete Webhook

Permanently remove:

• Click Delete
• Confirm deletion
• Cannot be undone

Monitoring

Delivery Status

Track webhook health:

• Success rate
• Average response time
• Recent failures
• Total deliveries

Alerts

Get notified:

• Multiple failures
• Slow responses
• Endpoint unreachable

Logs

View delivery history:

• Timestamp
• Event type
• Response code
• Response time
• Payload
• Error message (if failed)

Security

Best Practices

Always:

• ✅ Use HTTPS
• ✅ Verify signatures
• ✅ Validate payload
• ✅ Check event types
• ✅ Rate limit processing

Never:

• ❌ Use HTTP
• ❌ Skip signature verification
• ❌ Trust payload blindly
• ❌ Expose webhook URL publicly
• ❌ Include secrets in URL parameters

IP Whitelisting

Restrict to Batch IPs:

52.12.34.56
52.12.34.57
52.12.34.58

(Check dashboard for current IPs)

Advanced Use Cases

Event Streaming

Stream all events to data warehouse:

• BigQuery
• Snowflake
• Redshift
• S3 + Athena

Multi-System Sync

One webhook to multiple systems:

1. Receive webhook
2. Transform data
3. Fan out to:
   • CRM
   • Analytics
   • Email platform
   • Inventory system

Custom Workflows

Build complex automations:

order.created
  → Check inventory
  → Reserve stock
  → Notify fulfillment
  → Send confirmation email
  → Track in analytics

Troubleshooting

Webhooks Not Received

Check:

• Webhook active?
• Correct URL?
• HTTPS working?
• Firewall blocking?
• Event subscribed?

Failed Deliveries

Common Issues:

• Endpoint timeout
• Server errors (5xx)
• Invalid SSL certificate
• Network issues

Solutions:

• Optimize response time
• Fix server errors
• Renew certificate
• Check network/firewall

Duplicate Events

Causes:

• Retries after timeout
• Your system didn't respond

Handle:

• Use delivery ID
• Implement idempotency
• Deduplicate in queue

Related Resources