Simulated webhooks

How it works

The sandbox uses the same delivery engine as production:

Same payload structure — see the full contract
Same headers (x-event-id, X-NTXPay-Signature)
Same retry policy (5 attempts, exponential backoff, 10s timeout)
Same HMAC signature format

The difference is the origin: instead of waiting for real settlement on the SPEI network, the simulator resolves the transaction in seconds — and you control the outcome via scenarios. Webhook configuration is identical to production — register your URL via POST /api/webhooks-config as usual.

Two ways to trigger a webhook

1. Test webhook (no transaction)

The fastest way to validate your endpoint — it fires a signed delivery without moving anything:

curl -X POST https://sandbox.mx.ntxpay.com/api/webhooks-config/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "cash_in",
    "status": "LIQUIDATED"
  }'

The response tells you immediately whether your endpoint returned 2xx, the response time, and the signature that was sent. Vary the status (LIQUIDATED, PENDING, REJECTED, RETURNED) to exercise each path in your handler. Field details in Setup.

2. Simulated transaction (full flow)

Create a cash-in or cash-out with the X-Sandbox-Scenario header — the entire pipeline runs (balance, fee, statement) and the webhook arrives in seconds with the outcome you chose:

To receive	Use scenario	On webhook type
`*.settled` (`LIQUIDATED`)	`success` (or no header)	`cash_in` / `cash_out`
`*.settled` with ~30s delay	`pending_long`	`cash_in` / `cash_out`
`*.rejected` (`REJECTED`)	`rejected` or `insufficient_funds`	`cash_in` / `cash_out`
`*.returned` (`RETURNED`)	`returned` or `bad_clabe`	`refund_in` / `refund_out`

See the full scenario catalog.

Testing dedupe

Each delivery carries a unique x-event-id. To test your dedupe:

Configure your handler to return 500 on the first attempt.
NTX Pay will deliver the same message again (with the same x-event-id).
Confirm that your system ignores the duplicate and responds 200 on the second attempt.

Testing the signature

Point a test webhook at your endpoint and validate the X-NTXPay-Signature with the secret returned at creation:

import hmac
import hashlib

def verify(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Complete handlers in Node.js, Python, Java, and Go: Implementation.

Best practices

Validate the signature — always, even in the sandbox.
Use x-event-id for dedupe — the same event may be redelivered.
Do not rely on ordering — webhooks may arrive out of order after retries.
Exercise all four statuses before going to production — that is what the sandbox is for.

Guide

Sandbox

Webhooks

Authentication

SPEI

Webhooks Config

How it works

Two ways to trigger a webhook

1. Test webhook (no transaction)

2. Simulated transaction (full flow)

Testing dedupe

Testing the signature

Best practices

​How it works

​Two ways to trigger a webhook

​1. Test webhook (no transaction)

​2. Simulated transaction (full flow)

​Testing dedupe

​Testing the signature

​Best practices

How it works

Two ways to trigger a webhook

1. Test webhook (no transaction)

2. Simulated transaction (full flow)

Testing dedupe

Testing the signature

Best practices