Skip to main content
Webhooks are automated messages sent from Tonder when transaction events occur. Instead of repeatedly polling our API for status changes, webhooks provide real-time notifications the moment something happens—like a payment completing, failing, or requiring additional authentication. Using webhooks makes your integration more efficient and responsive, ensuring your system stays synchronized with transaction updates in real-time.

​
Key Events

Tonder sends webhook notifications for various transaction events:
Event TypeDescriptionExample Status Flow
Payment Status ChangesReal-time updates as payments progress through different statespending → authorized → success
Payment FailuresNotifications when payments are declined or failpending → declined or failed
3DS AuthenticationUpdates when users complete 3D Secure challengespending_3ds → success or failed
Cash Payment ConfirmationsNotifications when customers pay OXXO voucherspending → success (when paid at store)
Withdrawal UpdatesStatus changes for payout transactionsprocessing → success or failed

​
Webhook Payload Structure

API Direct webhooks use a flat payload — all fields are at the top level with no nested data wrapper. Here are the key fields:
FieldTypeDescription
idstringUnique identifier for this webhook event
operation_typestringType of operation (e.g., payment)
amountstringTransaction amount as a string
currencystringISO 4217 currency code (e.g., MXN)
client_referencestringYour own reference ID for the transaction
statusstringCurrent transaction status (e.g., Success, Pending, Failed)
providerstringPayment provider that processed the transaction
transaction_idstringTonder’s internal transaction identifier
payment_method_typestringPayment method used (e.g., SPEI, CARD, OXXO)
createdstringISO 8601 timestamp of when the event was created
metadataobjectCustom key-value pairs passed when the payment was created
event_typestringSpecific event that triggered this notification (e.g., payment_Success, payment_Pending)
actionstringAction associated with the event (e.g., MODIFY)
Here are examples of the two most common event types: 
{
  "id": "fc38522e-3e5d-45b8-ba6a-ece72caee71f",
  "operation_type": "payment",
  "amount": "70",
  "currency": "MXN",
  "client_reference": "f6d16280-7bff-4bb7-b6f1-967f9721248b",
  "status": "Success",
  "provider": "tonder",
  "transaction_id": "e9340a04-6d68-4afc-86c5-79f8b7c87de4",
  "payment_method_type": "SPEI",
  "created": "2026-05-21T19:15:32.029134Z",
  "metadata": {
    "order_id": "f6d16280-7bff-4bb7-b6f1-967f9721248b",
    "money_type": "rebet_cash",
    "external_id": "ec2d3598-f061-7081-11a4-a8afedce2ef7",
    "transaction_type": "deposit"
  },
  "event_type": "payment_Success",
  "action": "MODIFY"
}

​
Getting Started with Webhooks

To start receiving webhook notifications, you need to:
  1. Create a publicly accessible HTTPS URL that can receive POST requests.
  2. Secure your endpoint to verify requests come from Tonder.
  3. Register your endpoint using our API.
  4. Process incoming webhook notifications in your application.
Prerequisites for webhook endpoints:
  • Must use HTTPS (not HTTP) for security.
  • Should respond within 30 seconds to avoid timeouts.
  • Must return a 2xx status code to acknowledge receipt.
  • Should implement authentication to verify request source.

​
Reliability and Delivery

Tonder ensures reliable webhook delivery through built-in resilience mechanisms:
FeatureDetailsBenefit
Automatic RetriesUp to 3 delivery attempts with 60-second intervals between retriesHandles temporary outages and network issues
Response Timeout30-second timeout per delivery attemptPrevents hanging requests and ensures timely retries
Dead Letter QueueFailed events stored for 30 days with manual reprocessingNo events lost, manual recovery for persistent issues
Success CriteriaAny 2xx HTTP status code within timeout windowSimple and flexible acknowledgment requirements
For complete details on delivery mechanisms and retry policies, see Delivery and Retry Logic.

​
Common Use Cases

Here are practical examples showing how to implement webhook handlers for the most common scenarios you’ll encounter in production applications:
Handle payment status changes to automatically fulfill orders when payments complete or fail. Note that the API Direct payload is flat — all fields are at the top level.
@app.route('/webhook', methods=['POST'])
def handle_payment_webhook():
    payload = request.get_json()
    
    if payload['event_type'] == 'payment_Success':
        # Payment completed successfully
        fulfill_order(payload['client_reference'])
        
    elif payload['event_type'] == 'payment_Failed':
        # Payment failed
        cancel_order(payload['client_reference'])

    elif payload['event_type'] == 'payment_Pending':
        # Payment is awaiting confirmation (e.g., SPEI transfer in progress)
        mark_order_pending(payload['client_reference'])
    
    return jsonify({'status': 'received'}), 200
Process 3D Secure authentication completions to finalize payments that required additional customer verification.
@app.route('/webhook', methods=['POST'])
def handle_3ds_webhook():
    payload = request.get_json()
    
    if payload['event_type'] == 'payment_Success':
        # 3DS authentication successful, payment completed
        complete_order(payload['client_reference'])
    elif payload['event_type'] == 'payment_Failed':
        # 3DS authentication failed
        cancel_order(payload['client_reference'])
    
    return jsonify({'status': 'received'}), 200

​
Webhook Management

Now that you understand how webhooks work and have seen practical examples, explore these focused guides to implement webhooks in your application:

Setup & Management

Learn how to create, configure, and manage webhook endpoints through the API

Delivery & Retry

Understand how webhooks are delivered, retry policies, and handling failures

Best Practices

Security recommendations and implementation patterns for reliable webhooks