Listening for Channel webhooks

📘
In the previous guide, we discussed setting up a webhook listener. If you haven't configured your listener yet, please refer to that step to prepare for receiving webhooks.

Beem sends out a series of webhooks to keep you informed on any lifecycle event for the payment you have created.

The body of a webhook can be divided into three different sections, source, event , and data. Source will tell you the product source of the webhook, the event will be what event has occurred within that source, and data will be all of the relevant payment information sent with the webhook.

Source types:

For a channel payment, the source will always be channel.

Event types:

Event	Description
`layer1:payment:channel:transaction-confirmed`	The payment the end-user sent has been confirmed on the blockchain and funds have been credited to your merchant account.
`layer1:payment:channel:transaction-detected`	The end-user has sent a payment and it has been detected on the blockchain but has not yet had the required number of block confirmations.

Data types

Data in each webhook is comprehensive, but we will highlight some of the most important fields here:

Field	Description
`uuid`	UUID of the linked payment, will remain the same across all webhook types for that payment.
`status`	The current status of the payment.`COMPLETE` statuses are final.
`displayCurrency`	The display currency that the end user will see.
`paidCurrency`	The currency actually sent by the end user when fulfilling the payment.
`walletCurrency`	The wallet currency linked to the payment.
`paidAmount`	The amount sent by the end user when fulfilling the payment.
`displayAmount`	The amount sent by the end user in the display currency.
`walletAmount`	The amount sent by the end user in the wallet currency linked to the payment.

Payment Flow Diagram and Webhooks Sent

Payment Complete Webhooks

When an end user transmits cryptocurrency to a channel address, the following webhooks are sent out:

Webhook Event Name	Description
transaction-detected:	This webhook is issued as soon as a transaction is detected on the blockchain. It signifies the initial recognition of the payment sent to the channel address.
transaction-confirmed:	This webhook follows when the transaction achieves the necessary number of confirmations on the blockchain, ensuring its validity and finality

Channel webhooks are designed to address only the detection and confirmation stages of transactions. Given that the channel's address remains perpetually open to receive multiple payments, the concept of a 'payment completion' as with singular transactions does not apply in the same manner.

The transactionConfirmed webhook delivers comprehensive details about the channel payment. It includes the exact amounts transferred by the end user in the actual fields and the transaction hash. This hash can be utilized to verify the transaction details on a blockchain explorer, found within the transactions array.

Channel Webhooks

{
  "event": "layer1:payment:channel:transaction-detected",
  "source": "channel",
  "data": {
    "channelId": "326bf4e4-866e-4ec5-80e8-5233b7d29af5",
    "merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
    "merchantDisplayName": "ETH Merchant ",
    "reference": "Channel Test",
    "dateCreated": 1709556819750,
    "lastUpdated": 1709556819750,
    "status": "DETECTED",
    "uuid": "2d04095f-29b0-4434-89af-573759f8f248",
    "hash": "0x8ad672efcb337fb5a2025149e5e6f22e8af17f71b5270e904de28cee44de00e6",
    "address": "0xf210435eb347b9c79361b97fae333abf7cba1d9b",
    "tag": null,
    "paidCurrency": "ETH",
    "displayCurrency": "USD",
    "walletCurrency": "ETH",
    "feeCurrency": "ETH",
    "paidAmount": 0,
    "displayAmount": 0,
    "walletAmount": 0,
    "feeAmount": 0,
    "exchangeRate": null,
    "displayRate": null,
    "risk": {
      "level": "UNKNOWN",
      "resourceName": "UNKNOWN",
      "resourceCategory": "UNKNOWN",
      "alerts": []
    },
    "sources": null,
    "networkFee": {
      "paidCurrency": null,
      "paidAmount": 0,
      "displayCurrency": null,
      "displayAmount": 0
    }
  }
}

{
  "event": "layer1:payment:channel:transaction-confirmed",
  "source": "channel",
  "data": {
    "channelId": "326bf4e4-866e-4ec5-80e8-5233b7d29af5",
    "merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
    "merchantDisplayName": "ETH Merchant ",
    "reference": "Channel Test",
    "dateCreated": 1709556820000,
    "lastUpdated": 1709556909163,
    "status": "COMPLETE",
    "uuid": "2d04095f-29b0-4434-89af-573759f8f248",
    "hash": "0x8ad672efcb337fb5a2025149e5e6f22e8af17f71b5270e904de28cee44de00e6",
    "address": "0xf210435eb347b9c79361b97fae333abf7cba1d9b",
    "tag": null,
    "paidCurrency": "ETH",
    "displayCurrency": "USD",
    "walletCurrency": "ETH",
    "feeCurrency": "ETH",
    "paidAmount": 0.01234,
    "displayAmount": 43.28,
    "walletAmount": 0.01234,
    "feeAmount": 0.0001234,
    "exchangeRate": {
      "base": "ETH",
      "counter": "ETH",
      "rate": 1
    },
    "displayRate": {
      "base": "ETH",
      "counter": "USD",
      "rate": 3507.29
    },
    "risk": {
      "level": "UNKNOWN",
      "resourceName": "UNKNOWN",
      "resourceCategory": "UNKNOWN",
      "alerts": []
    },
    "sources": [
      "0x84a4a239805d06c685219801b82bea7c76702214"
    ],
    "networkFee": {
      "paidCurrency": "ETH",
      "paidAmount": 0.000033576139821,
      "displayCurrency": "USD",
      "displayAmount": 0.11
    }
  }
}