webhooks

Subscribing to Webhooks

To monitor the outcomes of charges and sessions, you can subscribe to webhooks through our platform.

Setting Up Webhooks

To set up a webhook, navigate to your Developer Dashboard and select the "Add Webhook" option. Keep in mind that you will need to use the Signing secret for each webhook you create to verify the signature.

You will receive a webhook notification each time there is an update to a charge or sessions.

Events

charge.updated:

This event will be triggered whenever there is a status update on a charge.

{
  "type": "charge.updated",
  "event_id": "c097c7c2-c6dc-44d8-bf98-75d2a4ee6a45",
  "occurred_on": 1664411628,
  "data": {
    "status": "succeeded",
    "id": "8aa109e7-b4aa-4b8a-97fd-fd247bcc160f"
  }
}

Property	Possible values	Description
type	charge.updated	Name of the event
event_id	UUID	The ID of the specific event
occured_on	int	Unix timestamp on when the event took place
data.status	pending | succeeded | failed	The new status of the charge
data.id	UUID	The ID of the charge that was updated

In this payload, data.id refers to the ID of the charge, and status indicates the current status of the charge. If you need more detailed information, you can query the API using the charge ID provided in the webhook.

session.paid:

This event will be triggered whenever a session is successfully paid.

{
   "type":"session.paid",
   "event_id":"6520c7df-8723-4783-9ba6-e8e1ff3e2721",
   "occurred_on":1664411628,
   "data":{
      "id": "8aa109e7-b4aa-4b8a-97fd-fd247bcc160f"
      "charge_id":"8aa109e7-b4aa-4b8a-97fd-fd247bcc160f"
   }
}

Property	Possible values	Description
type	session.paid	Name of the event
event_id	UUID	The ID of the specific event
occured_on	int	Unix timestamp on when the event took place
data.id	UUID	The ID of the session that was paid
data.charge_id	UUID	The ID of the charge that was created to pay the session

Webhook Security

Our webhooks include a signature to verify their authenticity. The following headers will be present in our webhooks and are used for signature verification:

• X-Nonce: 086b9d3f607a4b3e2e2818f5db3c1ff5
• X-Signature: 62ad115f0b8ef012b07d1b7fc…
• X-Timestamp: 1664411630
• X-Webhook-Id: 0551615f-2cb5-4cfd-865e-75bb24cc6219

Verifying the Signature

To verify the webhook signature, use the following steps depending on your programming language: Please note that you should use the Signing Secret found on your merchant dashboard for each webhook.

PHP:

$secret = '123123123';
$concat_header = "$timestamp|$nonce|$webhook_id";
$signature = hash_hmac('sha512', $concat_header, $secret);

Python:

secret = '123123123'
concat_header = f"{timestamp}|{nonce}|{webhook_id}"
signature = hmac.new(secret.encode(), concat_header.encode(), hashlib.sha512).hexdigest()

Go:

secret := "123123123"
concatHeader := fmt.Sprintf("%s|%s|%s", timestamp, nonce, webhookID)
h := hmac.New(sha512.New, []byte(secret))
h.Write([]byte(concatHeader))
signature := hex.EncodeToString(h.Sum(nil))

Compare the calculated $signature to the one provided in the webhook header to confirm authenticity.