Webhooks

Transacty sends webhook notifications to your server for pay-in and payout state changes.

Configure your webhook URL

PATCH/v1/me/webhook

Request fields

Field	Type	Required	Description
`webhookUrl`	`string \| null`	Yes	Merchant callback URL, or `null` to remove

Set URL


{
  "webhookUrl": "https://merchant.com/webhooks/transacty"
}

Disable


{
  "webhookUrl": null
}

cURL

curl -X PATCH https://api.transacty.ai/v1/me/webhook \
  -H "X-Transacty-Key: $TRANSACTY_KEY" \
  -H "X-Transacty-Timestamp: $TS" \
  -H "X-Transacty-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
  "webhookUrl": "https://merchant.com/webhooks/transacty"
}'

The response includes a webhookSecret. Store it securely — it is used to verify webhook signatures and is not shown again.

Events sent by Transacty

payin.completed
payin.failed
payout.completed
payout.failed

Webhook headers

Each webhook request includes:

X-Transacty-Webhook-Signature — an HMAC-SHA256 signature
X-Transacty-Event — the event type

Webhook payload example


{
  "event": "payin.completed",
  "transactionId": "uuid",
  "status": "success",
  "amount": "500",
  "paidAmount": "500",
  "platformOrderId": "2026031807000000129",
  "timestamp": "2026-03-19T10:00:00.000Z"
}

For failed events, paidAmount may be absent.

Signature verification

Use webhookSecret to verify the payload before processing:

Read the raw body

Read the raw request body exactly as received.

Compute the signature

Compute HMAC-SHA256(rawBody, webhookSecret).

Compare

Compare it with X-Transacty-Webhook-Signature.

Reject mismatches

Reject the request if the signature does not match.

Best practices

Process webhooks idempotently using transactionId.
Treat the webhook as the source of asynchronous state updates.
If a webhook is delayed, poll GET /v1/payins/:id or GET /v1/payouts/:id.