Webhooks

Webhooks provide real-time notifications about transaction status changes and allow you to configure endpoints for receiving these notifications. Tonder’s webhook system ensures reliable delivery of transaction updates through comprehensive retry mechanisms and authentication options.

Webhook Management

Manage webhook endpoints through the API to receive real-time transaction notifications.

Create Webhook

POST /webhooks/

Creates a new webhook endpoint for your business.

{
  "url": "https://your-site.com/webhook",
  "auth_method": "BEARER",
  "credentials": {
    "token": "your_bearer_token"
  }
}

List Webhooks

GET /webhooks/

Retrieves all webhook endpoints configured for your business.

[
  {
    "id": 123,
    "url": "https://your-site.com/webhook",
    "status": "active",
    "auth_method": "BEARER",
    "credentials": {
      "token": "your_bearer_token"
    }
  },
  {
    "id": 124,
    "url": "https://backup.your-site.com/webhook",
    "status": "inactive",
    "auth_method": "API_TOKEN",
    "credentials": {
      "header": "X-API-Key",
      "token": "your_api_key"
    }
  }
]

Update Webhook

PUT /webhooks/{webhook_id}/

Updates an existing webhook endpoint configuration.

{
  "url": "https://new-endpoint.com/webhook",
  "auth_method": "API_TOKEN",
  "credentials": {
    "header": "X-API-Key",
    "token": "new_api_key"
  }
}

Delete Webhook

DELETE /webhooks/{webhook_id}/

Removes a webhook endpoint from your business configuration. The server will respond with a 204 No Content status, indicating the webhook has been successfully deleted and there is no further information to return.

Test Webhook

POST /webhooks/{webhook_id}/test/

Tests webhook endpoint connectivity and updates status accordingly.

{
  "id": 123,
  "url": "https://your-site.com/webhook",
  "status": "active",
  "auth_method": "BEARER",
  "credentials": {
    "token": "your_bearer_token"
  }
}

Webhook Configuration

The following tables give you a quick overview of the available webhook authentication methods and status values.

Authentication Methods

These are the available webhook authentication methods.

Method	Description	Credentials Format
`BEARER`	Bearer token authentication	`{"token": "your_bearer_token"}`
`API_TOKEN`	Custom header with API key	`{"header": "X-API-Key", "token": "your_api_key"}`
`BASIC_AUTH`	HTTP Basic Authentication	`{"username": "user", "password": "pass"}`
`NONE`	No authentication	`{}` (not recommended for production)

Webhook Status

These are the available webhook status values.

Status	Description
`active`	Webhook is operational and receiving notifications
`inactive`	Webhook is configured but not receiving notifications
`error`	Webhook endpoint failed connectivity test

Webhook Events

Tonder sends webhook notifications for various transaction events:

Payment Events

Transaction status changes (pending → authorized → success)
Payment failures and declines
3DS authentication completions
Cash payment confirmations (OXXO, SafetyPay)

Withdrawal Events

Withdrawal processing updates
Payout completions and failures
SPEI transfer confirmations
Debit card deposit completions

Webhook Payload Structure

All webhook notifications follow a consistent payload structure:

{
  "event_type": "transaction.status_changed",
  "event_id": "evt_123456789",
  "created_at": "2024-07-26T10:32:15Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "operation_type": "payment",
    "status": "success",
    "previous_status": "authorized",
    "amount": 150.00,
    "currency": "MXN",
    "merchant_reference": "order-789",
    "payment_method": "CARD",
    "customer": {
      "name": "Ana María Rodríguez",
      "email": "ana.rodriguez@email.com"
    },
    "completed_at": "2024-07-26T10:32:15Z",
    "authorization_code": "AUTH123456"
  }
}

Where:

Field	Type	Description
`event_type`	string	Type of event that occurred
`event_id`	string	Unique identifier for this webhook event
`created_at`	string	ISO 8601 timestamp when event occurred
`data`	object	Transaction data and details
`data.status`	string	Current transaction status
`data.previous_status`	string	Previous transaction status

Implementation Examples

The following examples show how to implement webhook handling in different programming languages.

from flask import Flask, request, jsonify
import json
import logging

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    """Handle Tonder webhook notifications"""
    
    # Verify authentication based on your configured method
    if not verify_webhook_auth(request.headers):
        logging.warning("Webhook authentication failed")
        return jsonify({'error': 'Authentication failed'}), 401
    
    try:
        # Process webhook event
        event_data = request.get_json()
        result = process_webhook_event(event_data)
        
        if result:
            return 'OK', 200
        else:
            return jsonify({'error': 'Processing failed'}), 500
            
    except Exception as e:
        logging.error(f"Webhook processing error: {e}")
        return jsonify({'error': 'Processing failed'}), 500

def verify_webhook_auth(headers):
    """Verify webhook authentication"""
    
    # For BEARER: verify Authorization header
    auth_header = headers.get('Authorization')
    if auth_header and auth_header.startswith('Bearer '):
        token = auth_header[7:]
        return validate_bearer_token(token)
    
    # For API_TOKEN: verify custom header
    api_key = headers.get('X-API-Key')
    if api_key:
        return validate_api_key(api_key)
    
    # For BASIC_AUTH: verify basic authentication
    if auth_header and auth_header.startswith('Basic '):
        return validate_basic_auth(auth_header)
    
    return False

def process_webhook_event(event_data):
    """Process webhook event based on type"""
    
    event_type = event_data.get('event_type')
    transaction_data = event_data.get('data', {})
    
    transaction_id = transaction_data.get('id')
    status = transaction_data.get('status')
    operation_type = transaction_data.get('operation_type')
    
    logging.info(f"Processing webhook: {event_type} for {transaction_id}")
    
    if event_type == 'transaction.status_changed':
        return handle_status_change(transaction_data)
    else:
        logging.warning(f"Unknown event type: {event_type}")
        return True  # Return success for unknown events

def handle_status_change(transaction_data):
    """Handle transaction status change events"""
    
    transaction_id = transaction_data['id']
    new_status = transaction_data['status']
    previous_status = transaction_data.get('previous_status')
    operation_type = transaction_data['operation_type']
    
    try:
        if operation_type == 'payment':
            return handle_payment_status_change(transaction_data)
        elif operation_type == 'withdrawal':
            return handle_withdrawal_status_change(transaction_data)
        else:
            logging.warning(f"Unknown operation type: {operation_type}")
            return True
            
    except Exception as e:
        logging.error(f"Error handling status change for {transaction_id}: {e}")
        return False

def handle_payment_status_change(transaction_data):
    """Handle payment status changes"""
    
    transaction_id = transaction_data['id']
    status = transaction_data['status']
    merchant_reference = transaction_data.get('merchant_reference')
    
    if status == 'success':
        # Payment completed successfully
        update_order_status(merchant_reference, 'paid')
        send_confirmation_email(transaction_data)
        
    elif status == 'failed':
        # Payment failed
        update_order_status(merchant_reference, 'payment_failed')
        send_failure_notification(transaction_data)
        
    elif status == 'declined':
        # Payment was declined
        update_order_status(merchant_reference, 'payment_declined')
        send_decline_notification(transaction_data)
    
    return True

def handle_withdrawal_status_change(transaction_data):
    """Handle withdrawal status changes"""
    
    transaction_id = transaction_data['id']
    status = transaction_data['status']
    merchant_reference = transaction_data.get('merchant_reference')
    
    if status == 'success':
        # Withdrawal completed successfully
        update_payout_status(merchant_reference, 'completed')
        notify_beneficiary(transaction_data)
        
    elif status == 'failed':
        # Withdrawal failed
        update_payout_status(merchant_reference, 'failed')
        handle_payout_failure(transaction_data)
    
    return True

def validate_bearer_token(token):
    """Validate bearer token"""
    # Implement your token validation logic
    return token == "your_expected_bearer_token"

def validate_api_key(api_key):
    """Validate API key"""
    # Implement your API key validation logic
    return api_key == "your_expected_api_key"

def update_order_status(merchant_reference, status):
    """Update order status in your system"""
    # Implement your order status update logic
    pass

def send_confirmation_email(transaction_data):
    """Send payment confirmation email"""
    # Implement your email sending logic
    pass

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Webhook Delivery & Retry Logic

Tonder’s webhook service ensures reliable delivery of webhook notifications through AWS SQS-based retry mechanisms and comprehensive error handling. The following are the retry configuration for webhook delivery:

Setting	Value	Description
Maximum retry attempts	3	Each webhook delivery will be tried up to 3 times
Processing timeout	30 seconds per attempt	Each delivery attempt has a 30-second processing window
Visibility timeout	60 seconds between retries	60 seconds wait before a failed attempt is retried
Total retry window	Up to 3 minutes (3 × 60 seconds)	Maximum time spent retrying a single webhook
Message retention	14 days in the primary queue	Messages are kept for up to 14 days if not delivered

Retry Behavior

When a webhook delivery fails, the system automatically:

Logs the failure with detailed error information and attempt tracking
Returns the message to the SQS queue for retry
Waits 60 seconds before the next retry attempt becomes available
Repeats up to 3 times total

Failure Handling

These are the reasons why a webhook delivery is considered to have failed straight away:

Network connection errors
HTTP timeout (30 seconds)
Non-2xx HTTP response codes
Invalid webhook endpoints

Success Criteria

A webhook delivery is considered successful when:

HTTP response status is 2xx (200-299)
Response received within 30 seconds
No network or connection errors

Best Practices for Webhook Endpoints

Below are some best practices to help you build reliable, secure, and robust webhook endpoints.

Show Response Requirements

Respond quickly – Try to reply in under 5 seconds if you can.
Return the right status codes – Use 2xx for success, 4xx for permanent failures.
Handle timeouts gracefully – Make sure you process within 30 seconds, or use async processing if it might take longer.
Implement idempotency – Be ready for duplicate deliveries and handle them without causing issues.

Show Security Best Practices

Use HTTPS – Always use secure (HTTPS) endpoints for your webhooks.
Authenticate requests – Make sure you verify that webhook requests are actually from us.
Validate payloads – Double-check the event structure and content before processing.
Rate limiting – Protect your endpoints from abuse with sensible rate limits.

Show Error Handling

Log all events – Keep detailed logs so you can debug if something goes wrong.
Handle failures gracefully – Don’t let a dodgy payload crash your system.
Implement circuit breakers – Protect your downstream systems from overload.
Monitor webhook health – Set up alerts for repeated failures so you can jump in quickly.

Show Implementation Tips

Use queues – Process webhooks asynchronously where possible for better reliability.
Implement retries – Add retry logic for temporary failures in your own system.
Store event IDs – Keep track of event IDs to avoid processing the same event twice.
Test thoroughly – Make sure you test your webhook handling in all sorts of scenarios.

Testing Webhooks

There are two main approaches to testing webhook integration: local development testing and production environment testing. Use this code example to create a test endpoint that works for both local and production testing approaches:

Test Webhook Endpoint

@app.route('/webhook/test', methods=['POST'])
def test_webhook():
    """Simple test endpoint for webhook verification"""
    
    event_data = request.get_json()
    print(f"Received webhook: {json.dumps(event_data, indent=2)}")
    
    # Log the event
    logging.info(f"Test webhook received: {event_data.get('event_type')}")
    
    return 'OK', 200

Local Development Testing

Use this approach during development to test webhook integration:

Use ngrok for local testing: ngrok http 5000
Configure webhook URL with the ngrok URL
Process test transactions to trigger webhooks
Verify payload structure and authentication

Production Environment Testing

Use this approach to test webhooks in a production-like environment:

Test connectivity using the test webhook endpoint
Verify authentication works correctly
Check retry behaviour by temporarily returning errors
Monitor webhook logs for delivery success

Monitoring and Observability

The webhook service provides comprehensive logging for:

Individual delivery attempts with timing metrics
Retry attempt tracking (attempt_number, max_attempts, will_retry)
Performance metrics (request duration, processing time)
Failure analysis with exception details

To help you make sure everything’s running smoothly, follow this monitoring checklist:

Monitor webhook delivery success rates
Set up alerts for repeated failures
Track webhook processing times
Monitor endpoint uptime and availability
Review failed webhook logs regularly

Troubleshooting

These are the most common issues you might encounter and how to resolve them:

Issue	Cause	Solution
401 Authentication errors	Invalid credentials	Verify webhook authentication settings
404 Endpoint not found	Incorrect URL	Check webhook URL configuration
Timeout errors	Slow processing	Optimize webhook processing time
500 Server errors	Processing failures	Check webhook endpoint logs

To help you troubleshoot issues, follow these debugging steps:

Check webhook configuration - Verify URL and authentication
Test endpoint manually - Use curl or Postman to test
Review logs - Check both Tonder and your endpoint logs
Verify network connectivity - Ensure endpoint is accessible
Test with simple payload - Use webhook test endpoint

Next Steps

Review Error Handling for comprehensive error management
Check Production Readiness for webhook monitoring setup
Learn about Status Checking as a webhook backup
Explore Payment Methods for method-specific webhook events

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

Webhook Management

Create Webhook

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Webhook Configuration

Authentication Methods

Webhook Status

Webhook Events

Payment Events

Withdrawal Events

Webhook Payload Structure

Implementation Examples

Webhook Delivery & Retry Logic

Retry Behavior

Failure Handling

Success Criteria

Best Practices for Webhook Endpoints

Testing Webhooks

Local Development Testing

Production Environment Testing

Monitoring and Observability

Troubleshooting

Next Steps

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

​Webhook Management

​Create Webhook

​List Webhooks

​Update Webhook

​Delete Webhook

​Test Webhook

​Webhook Configuration

​Authentication Methods

​Webhook Status

​Webhook Events

​Payment Events

​Withdrawal Events

​Webhook Payload Structure

​Implementation Examples

​Webhook Delivery & Retry Logic

​Retry Behavior

​Failure Handling

​Success Criteria

​Best Practices for Webhook Endpoints

​Testing Webhooks

​Local Development Testing

​Production Environment Testing

​Monitoring and Observability

​Troubleshooting

​Next Steps

Webhook Management

Create Webhook

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Webhook Configuration

Authentication Methods

Webhook Status

Webhook Events

Payment Events

Withdrawal Events

Webhook Payload Structure

Implementation Examples

Webhook Delivery & Retry Logic

Retry Behavior

Failure Handling

Success Criteria

Best Practices for Webhook Endpoints

Testing Webhooks

Local Development Testing

Production Environment Testing

Monitoring and Observability

Troubleshooting

Next Steps