How Webhooks Work

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 Type	Description	Example Status Flow
Payment Status Changes	Real-time updates as payments progress through different states	`pending` → `authorized` → `success`
Payment Failures	Notifications when payments are declined or fail	`pending` → `declined` or `failed`
3DS Authentication	Updates when users complete 3D Secure challenges	`pending_3ds` → `success` or `failed`
Cash Payment Confirmations	Notifications when customers pay OXXO vouchers	`pending` → `success` (when paid at store)
Withdrawal Updates	Status changes for payout transactions	`processing` → `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:

Field	Type	Description
`id`	string	Unique identifier for this webhook event
`operation_type`	string	Type of operation (e.g., `payment`)
`amount`	string	Transaction amount as a string
`currency`	string	ISO 4217 currency code (e.g., `MXN`)
`client_reference`	string	Your own reference ID for the transaction
`status`	string	Current transaction status (e.g., `Success`, `Pending`, `Failed`)
`provider`	string	Payment provider that processed the transaction
`transaction_id`	string	Tonder’s internal transaction identifier
`payment_method_type`	string	Payment method used (e.g., `SPEI`, `CARD`, `OXXO`)
`created`	string	ISO 8601 timestamp of when the event was created
`metadata`	object	Custom key-value pairs passed when the payment was created
`event_type`	string	Specific event that triggered this notification (e.g., `payment_Success`, `payment_Pending`)
`action`	string	Action 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"
}

{
  "id": "b47faf2d-844e-4f14-bedd-f998a016cacd",
  "operation_type": "payment",
  "amount": "200",
  "currency": "MXN",
  "client_reference": "a38f5292-4c5e-42cd-aa73-15763d2d4862",
  "status": "Pending",
  "provider": "tonder",
  "transaction_id": "aa15fe61-a680-40b9-8546-4a98c204dc9d",
  "payment_method_type": "SPEI",
  "created": "2026-05-21T21:27:56.220201Z",
  "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_Pending",
  "action": "MODIFY"
}

Getting Started with Webhooks

To start receiving webhook notifications, you need to:

Create a publicly accessible HTTPS URL that can receive POST requests.
Secure your endpoint to verify requests come from Tonder.
Register your endpoint using our API.
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:

Feature	Details	Benefit
Automatic Retries	Up to 3 delivery attempts with 60-second intervals between retries	Handles temporary outages and network issues
Response Timeout	30-second timeout per delivery attempt	Prevents hanging requests and ensures timely retries
Dead Letter Queue	Failed events stored for 30 days with manual reprocessing	No events lost, manual recovery for persistent issues
Success Criteria	Any 2xx HTTP status code within timeout window	Simple 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:

Real-time Payment Status Updates

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

3DS Authentication Handling

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

Introduction

Direct Integration Guides

Webhooks

Reference Pages

Payment Methods

Resources

How Webhooks Work

Key Events

Webhook Payload Structure

Getting Started with Webhooks

Reliability and Delivery

Common Use Cases

Webhook Management

Setup & Management

Delivery & Retry

Best Practices

​Key Events

​Webhook Payload Structure

​Getting Started with Webhooks

​Reliability and Delivery

​Common Use Cases

​Webhook Management

Setup & Management

Delivery & Retry

Best Practices

Key Events

Webhook Payload Structure

Getting Started with Webhooks

Reliability and Delivery

Common Use Cases

Webhook Management