Sayswitch - Developer Documentation

Webhooks

Overview

Webhooks allow your application to receive real-time notifications about events that occur in your Sayswitch account. When an event occurs, we’ll send an HTTP POST request to your configured endpoint.

Setting Up Webhooks

Log into your Sayswitch Dashboard
Navigate to Settings > API Key > Webhook URL
Add your endpoint URL

Handling Webhook Events

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_PAYLOADSIGNATURE'];
$secretKey = 'your_secret_key';
 
// Verify signature
$expectedSignature = hash_hmac("SHA512", $payload, $secretKey);
if ($signature !== $expectedSignature) {
    http_response_code(400);
    exit('Invalid signature');
}
 
// Process event
$event = json_decode($payload, true);
 
switch ($event['type']) {
    case 'payment.success':
        // Handle successful payment
        break;
    case 'payment.failed':
        // Handle failed payment
        break;
}
 
http_response_code(200);
echo 'OK';
?>

const crypto = require('crypto');
 
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const payload = req.body;
  const signature = req.headers['payloadsignature'];
  const secretKey = 'your_secret_key';
  
  // Verify signature
  const expectedSignature = crypto.createHmac('sha512', secretKey).update(payload).digest('hex');
  if (signature !== expectedSignature) {
    return res.status(400).send('Invalid signature');
  }
 
  // Process event
  const event = JSON.parse(payload);
  
  switch (event.type) {
    case 'payment.success':
      // Handle successful payment
      break;
    case 'payment.failed':
      // Handle failed payment
      break;
  }
  
  res.status(200).send('OK');
});

import hmac
import hashlib
import json
 
@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.get_data()
    signature = request.headers.get('payloadSignature')
    secret_key = 'your_secret_key'
    
    # Verify signature
    expected_signature = hmac.new(secret_key.encode(), payload, hashlib.sha512).hexdigest()
    if signature != expected_signature:
        return 'Invalid signature', 400
    
    # Process event
    event = json.loads(payload)
    
    if event['type'] == 'payment.success':
        # Handle successful payment
        pass
    elif event['type'] == 'payment.failed':
        # Handle failed payment
        pass
    
    return 'OK', 200

Security

Signature Verification

Sayswitch uses HMAC SHA512 to sign webhook payloads. You should verify these signatures to ensure the webhook request is legitimate.

Formula: hash_hmac("SHA512", DATA, SECRET_KEY)

DATA: The raw webhook payload (body)
SECRET_KEY: Your merchant secret key
Header Name: payloadSignature

Best Practices

Verify Signatures
- Always verify webhook signatures using HMAC SHA512
- Use raw payload data (not parsed JSON) for signature verification
- Keep webhook secret secure and never expose it in client-side code
- Reject unverified requests immediately
Response Handling
- Respond quickly (within 5 seconds)
- Return HTTP 200 status for successful processing
- Process events asynchronously for complex operations
- Implement retry logic for failed processing
Security Considerations
- Use HTTPS endpoints only
- Validate payload structure after signature verification
- Implement rate limiting on webhook endpoints
- Log suspicious or malformed requests
Error Handling
- Handle duplicate events gracefully (idempotency)
- Log webhook events and responses
- Monitor failed deliveries
- Set up alerts for failures

Testing Webhooks

Local Testing
- Use tools like ngrok for local development
- Test signature verification with sample payloads
- Verify your HMAC SHA512 implementation

# Start ngrok on your webhook endpoint port
ngrok http 3000

Test Signature Verification

const crypto = require('crypto');
 
// Test your webhook signature verification
const testPayload = '{"test": "data"}';
const secretKey = 'your-test-secret-key';
const signature = crypto.createHmac('sha512', secretKey).update(testPayload).digest('hex');
 
console.log('Test signature:', signature);
// Use this signature in the payloadSignature header

<?php
// Test signature generation
$testPayload = '{"test": "data"}';
$secretKey = 'your-test-secret-key';
$signature = hash_hmac('SHA512', $testPayload, $secretKey);
 
echo 'Test signature: ' . $signature;
// Use this signature in the payloadSignature header
?>

import hmac
import hashlib
 
# Test signature generation
test_payload = '{"test": "data"}'
secret_key = 'your-test-secret-key'
signature = hmac.new(
    secret_key.encode(),
    test_payload.encode(),
    hashlib.sha512
).hexdigest()
 
print(f'Test signature: {signature}')
# Use this signature in the payloadSignature header

Test Events
- Use test API keys for development
- Trigger test events from your Sayswitch dashboard
- Verify event handling and signature validation
- Test different event types and edge cases

Troubleshooting

Common Issues:

Invalid Signature Errors
- Ensure you’re using the raw payload (not parsed JSON) for signature verification
- Verify you’re using the correct secret key from your dashboard
- Check that you’re using HMAC SHA512 algorithm
- Confirm the signature header name: payloadSignature
Connection Issues
- Verify webhook endpoint is accessible via HTTPS
- Check firewall and security group settings
- Ensure endpoint responds within 5 seconds
- Monitor response times and error rates
Event Processing
- Check webhook logs in your Sayswitch dashboard
- Verify payload structure matches expected format
- Implement proper error handling and logging
- Test with different event types

Need help? Contact support at developers@sayswitch.com

TV Validate