Webhooks

Use webhooks to be notified about events that happen in a Gluwa account.

You can receive a webhook notification from Gluwa when there is a transaction associated with your account. Note that Gluwa only notifies you if the transaction or an exchange was created by using Gluwa API.

To integrate Gluwa webhook to your service you need to:

1. Create a webhook endpoint and on your server

2. Register your webhook endpoint

3. Verify your address

Step 1: Create a Webhook Endpoint

Create an endpoint that would accept the webhook requests and process them according to your business logic.

Webhook is sent as a POST request to the URL you will register in Step 2. The webhook may or may not have a request body depending on the type of the event. For more information, see Supported Webhook Events.

Checking the veracity of a request using X-REQUEST-SIGNATURE

To verify that the webhook is actually sent by Gluwa, you must check the validity ofX-REQUEST-SIGNATURE header. This involves generating X-REQUEST-SIGNATURE value on your own server and comparing it against the value of the X-REQUEST-SIGNATURE header sent with the webhook.

To generate X-REQUEST-SIGNATURE:

1. Get your webhook secret from the Gluwa Dashboard Webhooks page

2. Get the request body you received

3. Run the following formula:

Generating X-REQUEST-SIGNATURE for a Webhook

Base64UrlSafeEncode(HMACSha256({request body in JSON string}, {webhook secret}))

The request body JSON string must be in minified format, meaning no spaces and line breaks between JSON keys and values.

Compare the resulting value with the X-REQUEST-SIGNATURE header from the webhook. If identical, you have successfully verified the signature.

Step 2: Register your webhook endpoint

The webhook will be sent to URLs that are registered through Gluwa Dashboard. Visit the page below to learn how to register your webhook endpoint.

You may use online webhook testing tools such as Webhook.site to test the webhook.

Webhooks

Step 3: Whitelist your wallet address

You will receive webhooks only for the events involving whitelisted wallet addresses. Visit the page below to learn how to whitelist your wallet address.

Addresses

Supported Webhook Events

Currently, we support webhooks for the following events:

1. Transaction Confirmed

2. Transaction Created

3. Transaction Failed

4. Exchange Success

5. Exchange Failed

If you generated your webhook secret prior to October 8th, 2020, see V1 webhook. Else, see V2 webhook.

Version 1 (V1) Webhook Events

Common Fields For All Webhook Requests

Attribute	Type	Description
EventType	string	The event type TransactionConfirmed, TransactionCreated, TransactionFailed, ExchangeSuccess, ExchangeFailed
Type	string	Always "Webhook"
ResourceID	string	The ID of the resource. For TransactionConfirmed, TransactionCreated, TransactionFailed, this is the transaction hash. For ExchangeSuccess, ExchangeFailed, this is the order ID

Transactions Related Events Only

Attribute	Type	Description
MerchantOrderID	string	The merchant order ID
Amount	string	The amount that was received.

Exchanges Related Events Only

Attribute	Type	Description
OrderAmountRemaining	string	Amount remaining in the order
Conversion	string	Conversion symbol for the order. See conversion.
SendingAddress	string	The address where the source amount was sent from.
ReceivingAddress	string	The address where the exchanged amount was received.
SourceAmount	string	The amount that was sent in source currency.
Price	string	The price used for the exchange. The unit is <exchanged currency>/<source currency>.
ExchangedAmount	string	The amount that was received in exchanged currency.

Version 2 (V2) Webhook Events

Common Fields For All Webhook Requests

Attribute	Type	Description
ID	UUID	The ID of the webhook.
CreatedDateTime	datetime	The created date and time of the webhook.
ResourceType	string	The type of the resource. Transaction, Exchange
EventName	string	The name of the event. TRANSACTION.CONFIRMED TRANSACTION.CREATED EXCHANGE.SUCCESS EXCHANGE.FAILED
Summary	string	The summary of the webhook.
Resource	obj	The resource associated with the webhook. This can be either: Transaction Exchange

Transaction

Attribute	Type	Description
ID	UUID	Gluwa's internal transaction ID.
TxHash	string	The created date and time of the webhook.
Source	string	The address of the sender.
Target	string	The address of the receiver.
Amount	string	Transaction amount, not including the fee. This is the amount that the receiver receives.
Fee	string	The fee amount.
Currency	string	The currency of the transaction. Webhook does not support BTC Transactions.
Status	string	The status of the transaction.Unconfirmed, Confirmed, or Failed. Unconfirmed - The transaction was announce to the blockchain, but is not included in any block yet. Confirmed - The transaction was included in the blockchain and received a confirmation. Failed - The transaction has failed for some reason.
MerchantOrderID	string	Used by the receiver of the receiver of the transaction to identify a payment. Supported by QR code payment feature only.
Note	string	A message attached to the transaction. It is an optional memo you can associate with the transaction.

Exchange

Attribute	Type	Description
ID	UUID	The ID of the order.
OrderAmountRemaining	string	Amount remaining in the order.
Conversion	string	Conversion symbol for the order. See conversion.
SendingAddress	string	The address where the source amount was sent from.
ReceivingAddress	string	The address where the exchanged amount was received.
SourceAmount	string	The amount that was sent in source currency.
Price	string	The price used for the exchange. The unit is <exchanged currency>/<source currency>.
ExchangedAmount	string	The amount that was received in exchanged currency.