Webhooks Documentation

Real-time event notifications for payments, orders, and account updates with signature verification.

Overview

Webhooks allow your application to receive real-time notifications when events happen in your Etail Depot account. Instead of polling our API, you can configure webhook endpoints to be notified immediately when events occur.

How it works:

Configure webhook endpoints in your dashboard
Events trigger HTTP POST requests to your endpoints
Verify webhook signatures for security
Process events and update your application state

Event Types

Payment Events

payment.succeeded - Payment completed successfully
payment.failed - Payment failed or was declined
payment.refunded - Payment was refunded

Order Events

order.created - New order placed
order.fulfilled - Order shipped or completed
order.cancelled - Order was cancelled

Account Events

account.updated - Account information changed
card.issued - New card was issued
transaction.created - New transaction recorded

Setup Guide

1. Create Webhook Endpoint

curl -X POST https://api.etaildepot.com/v2/webhooks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourdomain.com/webhooks/etaildepot",
    "events": ["payment.succeeded", "payment.failed"],
    "description": "Payment notifications"
  }'

2. Handle Webhook Events

// Node.js Express example
app.post('/webhooks/etaildepot', (req, res) => {
  const event = req.body;
  
  // Verify webhook signature
  const signature = req.headers['etail-signature'];
  if (!verifySignature(req.body, signature)) {
    return res.status(400).send('Invalid signature');
  }
  
  // Process the event
  switch (event.type) {
    case 'payment.succeeded':
      handlePaymentSuccess(event.data);
      break;
    case 'payment.failed':
      handlePaymentFailure(event.data);
      break;
  }
  
  res.status(200).send('OK');
});

3. Verify Signatures

const crypto = require('crypto');

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload, 'utf8')
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Event Structure

Webhook Payload Example

{
  "id": "evt_1234567890",
  "type": "payment.succeeded",
  "created": 1640995200,
  "data": {
    "object": {
      "id": "pay_1234567890",
      "amount": 10000,
      "currency": "USD",
      "status": "succeeded",
      "customer": {
        "id": "cust_12345",
        "email": "customer@example.com"
      }
    }
  },
  "request": {
    "id": "req_1234567890",
    "idempotency_key": null
  }
}

Best Practices

Security

• Always verify webhook signatures
• Use HTTPS endpoints only
• Validate event timestamps
• Store webhook secrets securely

Reliability

• Respond with 200 status quickly
• Implement idempotency checks
• Handle duplicate events gracefully
• Use retry mechanisms for failures

Need Help?

Developer Support

Get help with webhook implementation and troubleshooting.

Contact Support

Webhook Testing

Test webhook delivery and payload structure.

Test Webhooks