Introduction to Webhooks

To promptly notify users of transaction events and handle subsequent processing, we provide the Webhook feature.

Managing Webhook Endpoint

You can create, update, and delete webhook endpoints through the related API or the Management Dashboard.

Handling Webhook Events

Webhook notifications will be sent to the corresponding URL of the webhook endpoint in POST format with JSON content.

You need to listen for and receive Webhook notifications, and upon receiving a Webhook, you must return a server status code of 2xx to indicate successful receipt.

If your server does not correctly return 2xx, the webhook server will continuously resend the notification to your server within 5 hours, up to a maximum of 16 times. The first Webhook is pushed immediately, and the retry notification intervals are 10s, 30s, 1min, 2min, 3min, 4min, 5min, 6min, 7min, 8min, 9min, 10min, 20min, 30min, 1h, 2h, until you correctly respond with status 2xx or exceed the maximum retry count.

Verifying Webhook Signature (Optional)

To further ensure security, the Webhook provides signature verification. You need to verify that the notification is from the webhook service before updating your order status.

Signature Overview

Webhook notifications contain a signature field, which can be used to verify the legitimacy of the Webhook notification. The signature is placed in the custom field X-Signature of the header, and the signature is generated using the RSA private key with the RSA-SHA256 algorithm, output in base64 format.

Verifying Signature

Verifying the Webhook signature requires an RSA public key, which can be obtained from the management dashboard.

The steps to verify the signature are as follows:

Extract the signature field from the header and base64 decode it.
Obtain the raw data of the Webhook request.
Use the obtained Webhook notification, the RSA public key provided by the management platform, and the base64-decoded signature together in the RSA signature function for asymmetric signature computation to determine if the signature verification passes.

Taking golang as an example, the code for verifying the signature is as follows:

import (
	"crypto"
	"crypto/rsa"
	"crypto/x509"
	"encoding/pem"
	"errors"
	"log"

	"encoding/base64"
)

func verify(data []byte, publicKey []byte, signature string) (err error) {
	block, _ := pem.Decode(publicKey)
	if block == nil {
		return errors.New("public key error")
	}

	signBytes, err := base64.StdEncoding.DecodeString(signature)
	if err != nil {
		log.Printf("signature contain invalid charactors, %s", signature)
		return err
	}

	pub, err := x509.ParsePKCS1PublicKey(block.Bytes)
	if err != nil {
		return err
	}

	hashFunc := crypto.SHA256
	h := hashFunc.New()
	h.Write(data)
	hashed := h.Sum(nil)
	return rsa.VerifyPKCS1v15(pub, hashFunc, hashed, signBytes)
}