Skip to content
UnknownPay
ไทย
Webhooks

Webhook Overview

How UnknownPay notifies your server of terminal deposit and withdrawal states, and how to configure a webhook in the Portal

UnknownPay sends an HTTP POST to the URL you configure (your merchant endpoint) every time one of your deposits or withdrawals moves into an important terminal state. This lets your system reconcile orders in near real time — without polling.

Diagram coming soon — sequence diagram — customer transfers → UnknownPay matches/credits → POST webhook to merchant endpoint → merchant returns 2xx → UnknownPay marks delivered
Money reminder: every money field on a webhook payload is a baht string with 2 decimals, e.g. "100.50" (not a JSON number, not satang). Fields without a value yet (e.g. matched_amount before crediting) are null.
You configure the URL + secret in the Portal — the detailed steps live in Portal Preparation → Configure a webhook. This group focuses on payload structure, signature verification, and retry behavior.

Configure a webhook (in the Portal)

Webhook configuration is done through the Portal (not the S2S API) — enter the destination URL + select the events to receive. On a successful save the system issues a show-once signing secret; keep it to verify the signature on every request. The detailed steps live in Portal Preparation → Configure a webhook.

Diagram coming soon — Portal page for configuring the webhook URL + checkboxes to select events + a Test button + a show-once secret box

The events you can subscribe to: deposit.success, deposit.expired, withdrawal.success, withdrawal.rejected, withdrawal.failed, withdrawal.refunded.

In the Portal you also get:

  • Test button: sends a webhook.test event to your URL to confirm it is reachable.
  • Delivery log / replay: review past deliveries and re-send a failed event.

The next pages explain what each event's payload looks like, and how your endpoint must verify the signature and respond. See Event Catalog & Payloads, Signature Verification, and Endpoint Requirements, Retries & SSRF.

The webhook.test event

The "Test" button in the Portal sends an event with event_type = webhook.test. It carries a minimal payload ({"event_id":"test","event_type":"webhook.test"}) plus the header X-Webhook-Event-Id: test.

It only confirms that your endpoint is reachable and returns 2xx — it is not a real event and carries no transaction data.

You only receive events you have subscribed to — events you did not subscribe to are skipped (no POST, and not counted as a failure).

Bank List

Fetch the public bank master keyed by bank_code, used to set receiver_bank_provider on withdrawals

Event Catalog & Payloads

Every webhook event UnknownPay actually sends, plus the shared payload fields and real JSON examples for deposits and withdrawals