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:
Create a webhook endpoint and on your server
Register your webhook endpoint
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
:
Get your webhook secret from the Gluwa Dashboard Webhooks page
Get the request body you received
Run the following formula:
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.
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.
Supported Webhook Events
Currently, we support webhooks for the following events:
Transaction Confirmed
Transaction Created
Transaction Failed
Exchange Success
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
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
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
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
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.
Last updated