Using Webhook for Updates

Why Use Webhook

When building integrations with BasicEx, you may want your service to receive events from BasicEx so that your system can perform corresponding actions. For example, when using BasicEx Pay, you might want to perform certain actions after the completion of a ticket payment.

To enable Webhook events in BasicEx, you can pass a Webhook notification URL to specific BasicEx services, such as when creating a payment ticket or constructing a payout request. Depending on the specific service you're using, BasicEx can push real-time event data to the Webhook endpoint of your service as a part of POST requests. BasicEx sends Webhook events as JSON payloads of EVENT objects via HTTPS to your registered Webhook endpoint.

Webhook Events

BasicEx generates event data based on specific scenarios and sends this data to notify about certain activities.

Upon the occurrence of an event, BasicEx generates a new Event object. A single API request may result in the creation of multiple events. For example, when you create a payment ticket, depending on specific options, you may receive events such as invoice.paid, invoice.completed, and invoice.expired.

By registering a Webhook endpoint in BasicEx, you allow BasicEx to automatically send event objects as part of POST requests to the registered Webhook endpoint of your service. Upon receiving the event at your Webhook endpoint, your service can perform corresponding actions.

WARNING

Upon receiving a Webhook notification, you need to respond with an empty HTTP 200 body. Any other HTTP response is considered a failure. BasicEx servers will attempt to send Webhook pushes multiple times until successful or until BasicEx servers give up.

Event Object

The event object sent to your Webhook endpoint is structured as follows:

{
  "id": "500e8384-61b1-4219-855d-2a196330af52",
  "object": "event",
  "objectId": "40620230325105039975309362381014",
  "created": 1680064028243,
  "type": "invoice.completed",
  "data": {
    ......
  },
  "retriesNum": 0
}

Event Object Structure

Field Name	Type	Description
id	string	Event ID, unique for each Webhook event
objectId	string	ID carrying details of the Webhook event
object	string	Type of the Webhook event, default: event
created	long	Creation timestamp of the Webhook, (13 digits)
type	string	Notification event type of the Webhook, refer to: Event Type
data	object	Specific content of the Webhook event, depending on the event type
retriesNum	int	Number of retries for this Webhook event

Event Type

Type Name	Description
invoice.paid	Event notification when the payment ticket has been successfully paid. This event notification triggers after the payment ticket is paid, but it doesn't mean the ticket has been completed. Refer to the invoice.completed event notification for confirmation.
invoice.completed	Event notification when the payment ticket has been completed. This event notification triggers after the payment ticket is completed.
invoice.expired	Event notification when the payment ticket has expired. This event notification triggers after the payment ticket has expired.
payout.completed	Event notification for successful payouts. This event notification triggers after a payout is successful, representing a completed payout.
payout.failed	Event notification for failed payouts. This event notification triggers after a payout has failed.

Webhook Security Signature

To ensure that Webhook events originate from BasicEx, we strongly recommend that you verify the received Webhook events to confirm that they are initiated by BasicEx. BasicEx signs Webhook data using platform certificates and places the signed data in the X-Webhook-Signature header. The serial number of the certificate used for signing is included in the X-Webhook-Signature-Serial header.

To obtain the platform certificate, refer to the Get Platform Certificate Information endpoint to retrieve the current list of BasicEx platform certificates. Use the certificate serial number from the X-Webhook-Signature-Serial header to fetch the final signing certificate.

For developers, upon receiving a Webhook event, you need to verify the event securely. The process involves:

1. Retrieve the X-Webhook-Signature-Serial header and get the certificate information for the specified certificate serial number from the platform certificate list.

2. Concatenate the Webhook notification callback URL and the raw data stream (Webhook event data sent by BasicEx) to get the data that needs to be signed. For example:

   1. Webhook notification callback URL (corresponding to the notificationUrl passed when creating the order): https://***.com/webhook

   2. Webhook event content:

      {"id":"3a05d299-6a9d-44fb-90cb-f99347e2c0e6","objectId":"40820230831140740900502704128298","object":"event","created":"1693462063164","type":"payout.success","data":{"orderNo":"40820230831140740900502704128298","merOrderNo":"DAWWEQEQWRRFFF","currency":"USDT","totalAmount":"100.000000","tradeStartTime":"1693490860","chainPaymentInfo":null,"message":"","status":"completed"},"retriesNum":0}

   3. The example of the concatenated data body for signature is then (corresponding to the notificationUrl passed when creating the order):

      https://www.***.com/webhook{"id":"3a05d299-6a9d-44fb-90cb-f99347e2c0e6","objectId":"40820230831140740900502704128298","object":"event","created":"1693462063164","type":"payout.success","data":{"orderNo":"40820230831140740900502704128298","merOrderNo":"DAWWEQEQWRRFFF","currency":"USDT","totalAmount":"100.000000","tradeStartTime":"1693490860","chainPaymentInfo":null,"message":"","status":"completed"},"retriesNum":0}

3. Parse the public key information and signing algorithm from the certificate to be used for verification. Depending on your programming language, use the appropriate verification library, and verify the Webhook's origin using the certificate public key, signature, and the data to be signed.

You can also refer to our Webhook signature verification code in the BasicEx Java SDK for assistance in understanding the Webhook signature verification process.

Get Platform Certificate

Endpoint: https://openapi.basicex.com/v2/platform/certificate

Method: GET

Response Parameters:

Field	Type	Description
certificate	string	Platform certificate data
serialNumber	string	Platform certificate serial number

Troubleshooting

If you are not receiving or processing Webhooks as expected, please check the following:

• Verify that your Webhook handler's notificationURL can correctly receive POST requests.
• Ensure that your firewall is not blocking POST requests from servers it may not recognize.
• You can resend a Webhook by sending a POST with instructions associated with the specified ticket.