Webhooks

Webhooks are how we let you know the result of a purchase.

Whenever purchase events occur, we will make a POST request to your callback URL to let you know.

Configure your URL

To receive webhook events you must configure your callback URL.

note

We may have configured your callback URL for you, in which case you may not need to perform this step.

To configure your callback URL make an HTTP POST request to the following endpoint, {{baseUrl}}/merchant/auth/callback-url:

var axios = require('axios');
var data = JSON.stringify({ url: '{{callbackUrl}}' });

var config = {
    method: 'post',
    url: '{{baseUrl}}/merchant/auth/callback-url',
    headers: {
        Authorization: 'Bearer {{secret}}',
        'Content-Type': 'application/json',
    },
    data: data,
};

axios(config)
    .then(function (response) {
        console.log(JSON.stringify(response.data));
    })
    .catch(function (error) {
        console.log(error);
    });

Response:

{
    "message": "The callback URL has been configured",
    "success": true,
    "data": {
        "url": "{{callbackUrl}}"
    }
}

Events

We will notify you of the following purchase events via Webhook:

1. Successful: The purchase has been completed successfully.

2. Cancelled: The customer cancelled the purchase OR The customer left the purchase mid-process and after 1 hour of no further activity on the purchase we cancelled the purchase.

3. Declined: The customer's payment method was declined.

4. Failed: Something has gone wrong on our end and the purchase could not be completed.

5. Expired: The customer did not arrive at the payment page within 1 hour of preparing the purchase.

Example Event Body

The webhook event body will always be in the following format:

{
  "event": "EVENT_NAME",
  "echo": { ... }, // The body sent to us when originally preparing the purchase
  "purchase_id": "PURCHASE_ID"
}

{
  "event": "Cancelled",
  "echo": {
    "city": "Johannesburg",
    "email": "user@boodle.co.za",
    "amount": 150,
    "suburb": "Suburb",
    "complex": "The Complex",
    "province": "Gauteng",
    "cellphone": "+27834050182",
    "id_number": "3708014800085",
    "last_name": "Doe",
    "first_name": "Jane",
    "postal_code": "2101",
    "custom_field_1": "CUSTOM",
    "custom_field_2": "CUSTOM",
    "custom_field_3": "CUSTOM",
    "custom_field_4": "CUSTOM",
    "custom_field_5": "CUSTOM",
    "street_and_number": "Street 54",
    "customer_reference": "REFERENCE"
  },
  "purchase_id": 46
}

Verify our request

To verify the the request originated from Boodle perform the following process:

1. Stringify the event body
2. Create a SHA512 HMAC signature of the stringified body from step 1
3. Compare the result to the signature we sent along with the request via the X-Boodle-Signature HTTP header. If they match it means the request originated from Boodle.

Example code below to perform the verification using NodeJS:

const algorithm = crypto.createHmac('SHA512', {{secret}})
const signature = algorithm.update(JSON.stringify(req.body)).digest('hex');
const boodleSignature = req.headers['x-boodle-signature']
if (signature === boodleSignature) {
    // Do something with event
    const event = req.body;
}
res.send(200); // Respond successfully

Respond to our request

Return a 200 or 201 status code so that we know you have received our event.

If you do not acknowledge the event we will re-attempt to post the event to your callback URL a maximum of 10 times with exponential back-off.

Tip

If you're just getting familiarised with the webhook functionality, you could use https://webhook.site/ to test the webhooks you're receiving without doing any major development on your backend.