# Webhooks 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](https://docs.gluwa.com/get-started/dashboard/webhooks#register-webhook-endpoint). The webhook may or may not have a request body depending on the type of the event. For more information, see [Supported Webhook Events](#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 of`X-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](https://dashboard.gluwa.com/Webhook) page 2. Get the request body you received 3. Run the following formula: {% code title="Generating X-REQUEST-SIGNATURE for a Webhook" %} ```csharp Base64UrlSafeEncode(HMACSha256({request body in JSON string}, {webhook secret})) ``` {% endcode %} {% hint style="warning" %} The request body JSON string must be in minified format, meaning no spaces and line breaks between JSON keys and values. {% endhint %} 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](https://dashboard.gluwa.com). Visit the page below to learn how to register your webhook endpoint. You may use online webhook testing tools such as [Webhook.site](https://webhook.site/) to test the webhook. {% content-ref url="../get-started/dashboard/webhooks" %} [webhooks](https://docs.gluwa.com/get-started/dashboard/webhooks) {% endcontent-ref %} ## 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. {% content-ref url="../get-started/dashboard/addresses" %} [addresses](https://docs.gluwa.com/get-started/dashboard/addresses) {% endcontent-ref %} ## 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 {% hint style="info" %} If you generated your webhook secret prior to October 8th, 2020, see [V1 webhook](#version-1-v-1-webhook-events). Else, see [V2 webhook](#version-2-v-2-webhook-events). {% endhint %} ### 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](https://docs.gluwa.com/api/currency-and-conversion-symbols#conversion-symbols). | | 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 `/`. | | 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:

  1. Transaction
  2. 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](https://docs.gluwa.com/api/currency-and-conversion-symbols#conversion-symbols). | | 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 `/`. | | ExchangedAmount | `string` | The amount that was received in exchanged currency. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gluwa.com/development/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.