webhook events

as the name implies, callback events are triggered whenever the payment status of an order changes. before utilizing the webhook, ensure that you've set the signature key value in our admin portal.

divit will send notifications under the following state changes. note that if you're using a direct payment request, you won't receive the expiry event:

event	description	method 1	method 2	method 3
2001 payment success	sent when the payment is completed	Y	Y	Y
4001 payment expired	sent when the payment has expired	Y	Y	Y
4000 payment cancelled	sent when the payment is cancelled, user cancelled and returned to merchant website	Y	-	-

info

additional webhooks could be sent if you have custom integration with divit.

caution

if your website offers multiple payment methods besides divit, be aware that users might switch between different payment options. if a user ultimately chooses another payment method, the payment order created at divit will expire. However, your server will still receive our expiry event for that order.

here is the event payload structure

{
  "event":{
    "eventId":2001,   // event code
    "eventDescription":"Order is paid"
  },
  "eventData":{
    "orderID":"87418689-8f26-4200-8d6e-8c4430b41759",     // divit order ID - {{DIVIT_ORDER_ID}}
    "customerID":"4303d849-aaf5-4d1d-8391-edbce9dcd350",  // available for method 1 only
    "totalAmount":{"amount":150000,"currency":"HKD"},
    "partnerRef":"DT-20220803-001"
  }
}

info

if you are using method 2, 3. the webhook event is the only way you get the "divit order ID", which you can use it to execute a refund request when necessary.

verifying webhook event

all events are signed using a hmac-sha256 signature. the signature is created using HMAC-SHA256.

X-DIVIT-SIGNATURE:t={{EVENT_TIMESTAMP}},s1={{SIGNATURE}}

• EVENT_TIMESTAMP is a unix timestamp from when the event was sent. This timestamp is also embedded in the signature to top replay attacks.
• SIGNATURE The HMAC-SHA256 hashed timestamp+body

validate signature

to validate the signature, we need to be able to create the same hash as in the header signature. you can achive that using three pieces of information

• EVENT_TIMESTAMP
• SIGNATURE
• EVENT_BODY
• shared signature secret key (Which you get from your divit representative)

step 1: extract EVENT_TIMESTAMP and SIGNATURE

split the header content by the , and again by =. This will give you EVENT_TIMESTAMP and SIGNATURE

step 2: recreate signature content

the signature content has the format of the combined string EVENT_TIMESTAMP.EVENT_BODY where EVENT_BODY is the JSON that was sent from divit webhook.

step 3: calculate the hash of the content

calculate EVENT_TIMESTAMP.EVENT_BODY with the predefined signature key (setup at the admin portal of divit). here are some code samples for your reference.

php

  // extract from header X-DIVIT-SIGNATURE
  $signatureFromHeader = "t=1683611281,s1=xK3ElZharJjt9PJXq7q4JevPHRTafKmIoXAwiWNw9yQ=";
  // extract timestamp from header
  $timestamp = substr($signatureFromHeader, 2, strpos($signatureFromHeader, ",s1=")-2);
  // extract signature from header
  $signature = substr($signatureFromHeader, strpos($signatureFromHeader, ",s1=")+4);

  // event body
  $bodyStr = '{"event":{"eventId":2001,"eventDescription":"Order is paid"},"eventData":{"orderID":"87418689-8f26-4200-8d6e-8c4430b41759","customerID":"4303d849-aaf5-4d1d-8391-edbce9dcd350","totalAmount":{"amount":150000,"currency":"HKD"},"partnerRef":"DT-20220803-001","deliveryAddress":null}}';

  // signatureKey = api-key
  $signaturekey = "dvt_Iw9lMfIq4m0KD0ctKeEyrawEWIbvW9kGNhbn";

  // content to be verified
  $signatureContent = $timestamp.".".$bodyStr;

  $result = base64_encode(hash_hmac('sha256', $signatureContent, $signaturekey, true));
  if ($signature == $result) {
    echo("passed");
  } else {
    echo("failed");
  }

golang

  func TestSignature(t *testing.T) {  
    // extract from header X-DIVIT-SIGNATURE
    signatureFromHeader := "t=1683611281,s1=xK3ElZharJjt9PJXq7q4JevPHRTafKmIoXAwiWNw9yQ="
    // extract timestamp from header
    timestamp := signatureFromHeader[2:strings.Index(signatureFromHeader, ",s1=")]
    // extract signature from header
    signature := signatureFromHeader[strings.Index(signatureFromHeader, ",s1=")+4:]

    // event body
    bodyStr := `{"event":{"eventId":2001,"eventDescription":"Order is paid"},"eventData":{"orderID":"87418689-8f26-4200-8d6e-8c4430b41759","customerID":"4303d849-aaf5-4d1d-8391-edbce9dcd350","totalAmount":{"amount":150000,"currency":"HKD"},"partnerRef":"DT-20220803-001","deliveryAddress":null}}`

    // signatureKey = api-key
    signaturekey := "dvt_Iw9lMfIq4m0KD0ctKeEyrawEWIbvW9kGNhbn"

    // content to be verified
    signatureContent := fmt.Sprintf("%s.%s", timestamp, bodyStr)

    h := hmac.New(sha256.New, []byte(signaturekey))
    h.Write([]byte(signatureContent))
    calculatedSignature := base64.StdEncoding.EncodeToString(h.Sum(nil))
    if signature == calculatedSignature {
      t.Log("passed")
    } else {
      t.Log("failed")
    }
  }

---

event list

order activated - ID:2001

this event is triggered when a user successfully 'activates' an order. this means that the user has been accepted by divit. When this event is received, then you can confirm with the user that payment is complete and they can receive their product.

sample event

POST / HTTP/1.1
Host: {{YOUR_WEBHOOK_ENDPOINT}}
Accept: application/json
Accept-Encoding: gzip
Content-Length: 279
Content-Type: application/json; charset=utf-8
X-Divit-Signature: t=1683611281,s1=7ceJBJKe3TpZY55u3NxQldIDtL7LdcujDPFM7B53Bgw=

{"event":{"eventId":2001,"eventDescription":"Order is paid"},"eventData":{"orderID":"87418689-8f26-4200-8d6e-8c4430b41759","customerID":"4303d849-aaf5-4d1d-8391-edbce9dcd350","totalAmount":{"amount":150000,"currency":"HKD"},"partnerRef":"DT-20220803-001","deliveryAddress":null}}

order is cancelled - ID:4000

this event is triggered when a user cancelled the payment and getting back to merchant website.

order is expired - ID:4001

this event is triggered when a the payment is expired.