Webhooks

eTax Gateway receives webhooks from payment providers. These webhooks are verified using HMAC-SHA256 signatures before processing.

KBank Webhook

POST /api/webhooks/payments/kbank

KBank sends a signed webhook when a payment status changes.

Signature Verification

The gateway verifies every request using HMAC-SHA256:

signature = HMAC-SHA256(secret, "{timestamp}.{body}")

secret — The KBANK_WEBHOOK_SECRET configured on the server
timestamp — Value of the X-Kbank-Timestamp header (ISO 8601)
body — Raw JSON request body string

Request Headers

Header	Description
`X-Kbank-Timestamp`	ISO 8601 timestamp (e.g. `2026-03-09T10:00:00.000Z`)
`X-Kbank-Signature`	HMAC-SHA256 hex string
`Content-Type`	`application/json`

Request Body

Field	Type	Description
`eventId`	string	KBank event ID (must be unique)
`eventType`	string	Event type (e.g. `PAYMENT_STATUS`)
`status`	string	Payment status from KBank
`providerReference`	string	KBank's payment reference

Example (bash)

TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
BODY='{"eventId":"evt-001","eventType":"PAYMENT_STATUS","status":"SUCCESS","providerReference":"KBANK-12345"}'
SECRET="your-webhook-secret"
MESSAGE="${TIMESTAMP}.${BODY}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://dev-etax.siamprop.app/api/webhooks/payments/kbank \
  -H "Content-Type: application/json" \
  -H "X-Kbank-Timestamp: $TIMESTAMP" \
  -H "X-Kbank-Signature: $SIGNATURE" \
  -d "$BODY"

Response — 200 OK

{ "received": true }

Error Cases

errorCode	HTTP	Cause
`WEBHOOK_SIGNATURE_INVALID`	401	Signature mismatch or missing headers
`VALIDATION_ERROR`	422	Malformed request body