Skip to main content

webhook events

as the name suggests, order events are sent whenever an order has changed state and you have subscribed to a notification. these events are usually related to the different payment states of the order. before you using the webhook, make sure you have created your signature secret at our partner-portal

security​

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 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, by default it is the api-key). here are some code samples for your reference.


  // 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");
  }

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
{
  "event": {
    "eventId": 2001,
    "eventDescription": "Order has been activated by the customer"
  },
  "eventData": {
    "orderID": "7f32674f-6f8a-407d-934c-768d84472a76",
    "customerID": "<divit-customer-uuid>",
    "totalAmount": {
      "amount": 400253,
      "currency": "HKD"
    },
    "partnerRef": "INTERNAL-REF-12121"
  }
}

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.