Webhooks

Webhooks allow you to get notifications that happen on your workspace. You might use webhooks to top up user balance when a payment complete, or to email a customer when a payment has been made

You can 'listen' for events that occur in your workspace at your chosen URL, where all event types will be broadcasted.

Webhook URL requirement:

Each webhook URL must be a complete, globally available HTTPS address (e.g., https:// example.com).

Events are sent to your webhook endpoint URL associated with the workspace, as part of a POST request with a JSON payload.

Webhook types:

There are 4 webhook types:

Received

The Received webhook will be sent when the payment process is started and transaction is found in a blockchain. This message is for informational purposes only and can be ignored.

The Received webhook payload example:

{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETHETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": null,
		"quoteCurrency": "USDT_TRX",
		"status": "Received",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Received",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}

Confirmed

The Confirmed webhook will be sent when the transaction is confirmed in a blockchain.

The Confirmed webhook payload example:

{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": null,
		"quoteCurrency": "USDT_TRX",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}

Completed

The Completed webhook will be sent when the payment process is completed, but not settled yet.

The Received webhook payload example:

{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": 5500,
		"quoteCurrency": "USDT_TRX",
		"status": "Completed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}

Settled

The Settled webhook will be sent when the payment process is completed, funds are settled and available to withdraw.

The Settled webhook payload example:

{
	"solution": "Commerce",
	"type": "Deposit",
	"trackingId": "User#123",
	"invoice":
	{
		"id": 355855,
		"uId": "Drm6zrRoqCFbrZH4OzkioDSE",
		"label": "ETH test invoice",
		"walletId": 323,
		"expectedAmount": 3,
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"payment":
	{
		"id": 134755,
		"baseAmount": 2.15,
		"baseCurrency": "ETH",
		"quoteAmount": 5500,
		"quoteCurrency": "USDT_TRX",
		"status": "Settled",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	},
	"transaction":
	{
		"id": 14574755,
		"amount": 2.15,
		"currency": "ETH",
		"address": "0x07CF3F636A3D0951Ec0571ce6cEaFf142baa7cA3",
		"tag": null,
		"hash": "0xb1bb8e05c93a010419349ee8c2ef241c0a64d1319ef8edb9afe2fc734aETH005",
		"status": "Confirmed",
		"createdAt": "2023-05-16T12:09:03.000000Z"
	}
}

Verifying the signature of incoming webhooks

An incoming webhook request has a header that should be used to verify the payload has not been tampered with.

The name of the header containing the signature - "Signature". The webhook is sent by a POST request, which contains JSON payload.

$computedSignature = hash_hmac('sha256', $payloadJson, $secret);

If the computedSignature and received signature does match return 200 http code after processing the payload.

If your server is temporarily unavailable or the status of the response is different from 200, we will resend the webhook several times with the increasing delay time.