Webhooks to get real-time updates
Hola Cash uses Webhooks to notify you of callbacks. These are delivered as JSON payloads via HTTPS. You can use these notifications to react to different events and execute actions on your app. For example, imagine you've received a webhook notifying you that an order payment has been made. You can then send a message to your warehouse to dispatch the order.
How to receive Webhooks from Hola Cash
- Login to the Merchant portal using your credentials.
- Navigate to the Developers menu.
- Create a webhook endpoint as an HTTPS endpoint (URL).
- The new webhook will appear on the Webhooks list. You can modify your webhook at any time or add new webhooks URLs.
- Use the Webhook Key to validate the Webhooks coming from Hola Cash. This is an important step because it allows you to know that the event is coming from Hola Cash and not from a malicious third-party.
How to validate a Webhook from Hola Cash
Built-in retries
Hola Cash webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. Hola Cash expects a 2xx http response at all times.
The webhooks you receive from us will contain the HOLACASH-SIGN header which is a string separated by a comma. See the example below:
1648551779.84847,EB9A452AFCBA258FF718033A6964336B7C8AC4318E5533DDEFCC3BB99FEDA079
The first half of the value is a timestamp representing when the webhook was sent. The second part is a hexadecimal representation of an HMAC-SHA256 hash.
You should verify this hash on your end to make sure that you're processing a webhook generated by Hola Cash, for which you will need a webhook key. Since the webhook key is a shared secret, it needs to be stored safely.
Verify the signature using the following algorithm:
- Retrieve the HOLACASH-SIGN HTTP header.
- Let's assume that you store the time stamp in a variable called timestamp.
- Split the values and store them in separated variables.
- Retrieve the HTTP Body. Verify that is a valid JSON.
- Store the JSON object as a string without any needed spaces. We recommend using stringify in JavaScript to correctly convert the JSON to a string. If you're using Python you:
- Concat the timestamp a dot (“.”) and the string payload
- Use your webhook key to sign the concatenated string with the HMAC-SHA256 algorithm.
- Compare the obtained signature with the one you received in HOLCASH-SIGN header. Use a crypto library to compare the hashes. Avoid string comparison.
json.dumps(payload), separators=(',',';'))
{
"event_type":"charge.succeeded",
"payload": {
"id": "935e0646-a0de-4acf-9954-542b2a97e5f9",
"status_details": {
"status": "success",
"message": "charge created",
"date_created": 1648551779704,
"detail": {
"code": null,
"message": null,
"additional_details": [
{
"name": "card_brand",
"data": "visa"
},
{
"name": "card_type",
"data": "credit"
},
{
"name": "card_bin",
"data": "424242"
},
{
"name": "card_last_four_digits",
"data": "4242"
},
{
"name": "currency_code",
"data": "MXN"
},
{
"name": "expiration_year",
"data": "23"
},
{
"name": "expiration_month",
"data": "12"
},
{
"name": "charge_status",
"data": "captured"
}
]
}
},
},
"charge": {
"description": "testing",
"amount_details": {
"amount": 4500,
"currency_code": "MXN"
},
"payment_detail": {
"credentials": {
"payment_method": {
"method": "credit_or_debit_card",
"display_name": null,
"logo": null
},
"holacash_payment_token": null,
"credit_or_debit_card": {
"card_number": "424242XXXXXX4242",
"expiration_month": "12",
"expiration_year": "2023",
"card_validation_code": "XXX"
},
"pay_by_store_type": null
},
"address": null,
"contact": null,
"name": null
},
"processing_instructions": {
"auto_capture": true
},
"purchase_details": {
"external_system_order_id": null,
"holacash_system_order_id": "a85610ac-4eab-444d-97d8-4e610011be5e",
"holacash_system_order_id": "a85610ac-4eab-444d-97d8-4e610011be5e",
"order_data": null
},
"consumer_details": {
"external_consumer_id": null,
"address": null,
"contact": {
"phone_1": "13212312412",
"email": "asdasd@holacash.mx",
"additional_contact_info": null
},
"name": {
"first_name": "asdasd",
"second_first_name": null,
"first_last_name": null,
"second_last_name": null
}
},
"shipping_details": null,
"additional_details": null
},
"related_transactions": null,
"additional_detail": null
}
}
stringToSign = timestamp + "." + json_as_string
Both signatures should be identical. Any request with an invalid signature should be discarded.
Signature validation code samples
You can check sample signature validations in here under the folder of your preferred language with the filename webhook_signature