How It Works

1. Partner Registration: Partners receive an API key and secret for authentication
2. Event Submission: Partners send JSON payloads with proper authentication headers
3. Validation: The service validates signatures, timestamps, and rate limits
4. Processing: Valid events are stored and processed asynchronously
5. Status Tracking: Partners can query the status of their submitted events

API Endpoints

Authentication

Signature Generation

Generate the webhook signature using HMAC-SHA256:

# Generate timestamp
TIMESTAMP=$(date +%s)

# Create signature payload
PAYLOAD='{"id":"evt_123","type":"order.created","data":{...}}'
SIGNATURE_PAYLOAD="${TIMESTAMP}.${PAYLOAD}"

# Generate HMAC-SHA256 signature
SIGNATURE=$(echo -n "$SIGNATURE_PAYLOAD" | \
  openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

# Include in request headers
x-webhook-signature: sha256=${SIGNATURE}
x-timestamp: ${TIMESTAMP}

JavaScript Example

const crypto = require('crypto');

async function sendWebhookEvent(apiKey, secret, eventData) {
  // Generate timestamp
  const timestamp = Math.floor(Date.now() / 1000).toString();
  
  // Prepare the payload
  const payload = JSON.stringify(eventData);
  
  // Create signature
  const signaturePayload = `${timestamp}.${payload}`;
  const signature = crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');
  
  // Send the request
  const response = await fetch('https://api.example.com/api/webhooks/events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'x-webhook-signature': `sha256=${signature}`,
      'x-timestamp': timestamp
    },
    body: payload
  });
  
  return response.json();
}

// Example usage
const event = {
  id: 'evt_' + Date.now(),
  type: 'order.created',
  data: {
    orderId: 'ORD-456',
    amount: 99.99
  }
};

sendWebhookEvent('your_api_key', 'your_secret', event)
  .then(result => console.log('Event sent:', result))
  .catch(error => console.error('Error:', error));

cURL Example

curl -X POST https://api.example.com/api/webhooks/events \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -H "x-webhook-signature: sha256=abc123..." \
  -H "x-timestamp: 1635360000" \
  -d '{
    "id": "evt_123",
    "type": "order.created",
    "data": {
      "orderId": "ORD-456",
      "amount": 99.99
    }
  }'

Response Status Codes

• 200 OK - Event received and queued for processing
• 400 Bad Request - Invalid request format or JSON
• 401 Unauthorized - Invalid API key or signature
• 403 Forbidden - IP address not allowed
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error occurred

Best Practices

• Store your API secret securely and never expose it in client-side code
• Implement retry logic with exponential backoff for failed requests
• Include unique event IDs to ensure idempotency
• Keep timestamps synchronized with NTP to avoid signature validation failures
• Monitor your rate limit usage to avoid disruptions