Webhook Notifications
Set up webhooks to get real-time updates on events within the API.
Acquired.com uses webhooks to notify your application when events occur, such as, the final status of the payment is known. We deliver webhook notifications to the URI endpoint configured in the Hub. A webhook is an automatic notification that we can send directly to your system after an event takes place against your account. Webhooks are server to server notifications unaffected by potential issues with the front end system and user error.
Note
If your firewall blocks incoming requests, you might need to add our IP addresses to allow you to receive webhooks.
Webhook structure
Each webhook may contain the following headers:
Header | Type | Description |
---|---|---|
Content-Type | string | The media type of the resource: application/json |
Company-Id | string | The GUID Company ID associated with the event. |
Mid | string | The GUID Mid ID associated with the event. (not required for customer_new and card_new ) |
Webhook-Version | string | The version of the webhook body schema. |
Hash | string | The calculated hash value. |
The webhook body may contain the following parameters:
Note
To view the specific structure of each webhook type, please refer to the webhook detail documentation below.
Field | Type | Description |
---|---|---|
webhook_type | string | Describes the type of event: status_update customer_new card_new |
webhook_id | string | UUID assigned by Acquired.com for the notification. |
timestamp | integer | Exact date of when the webhook was delivered in UNIX timestamp format. |
webhook_body | JSON object | NA |
transaction_id | string | UUID assigned by Acquired.com for the payment. Implementations should be able to handle blank transaction ID values, since payments can be "cancelled" by users before this value is generated. |
status | string | The final status for the payment. (To view a list of all statuses, click here.) |
order_id | string | The order ID value that was passed by you in the payment request. |
customer_id | string | UUID assigned by Acquired.com for the customer. |
card_id | string | UUID assigned by Acquired.com for the card. |
Validate the integrity of the webhook
We use HMAC_SHA256 to safeguard the integrity of JSON webhook messages. In a single step, we include the complete message alongside the app_key
for verification purposes. Upon receiving the webhook, comparing the generated hash with the received hash helps ensure data integrity. A match between the hashes signifies that the JSON payload remains unaltered, confirming the data's integrity.
Follow the below steps to calculate the hash value:
- Obtain the JSON payload message from the posted webhook and append your
app_key
.
"app_key", {"webhook_type": "status_update", "webhook_id": "bc25b699-ffb1-40d5-b508-f6a28aeb18eb", "timestamp": 32908394083, "webhook_body": {"transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0", "status": "cancelled", "order_id": "6234ae00-1352-4bd7-872a-f328df1b7096" }}"
- HMAC_SHA256 encrypt the resulting string.
bece0bdfcfcb96364e31c653d115731545c3d2a8cdbde73aedff2b085117c30e
- Compare the generated
hash
value, to the previously returnedhash
value.
Webhook detail
This section provides detailed information on each webhook within the Acquired.com system.
status_update
status_update
The status_update
webhook provides the merchant with the current status of the payment request.
{
"webhook_type": "status_update",
"webhook_id": "bc25b699-ffb1-40d5-b508-f6a28aeb18eb",
"timestamp": 32908394083,
"webhook_body": {
"transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
"status": "cancelled",
"order_id": "6234ae00-1352-4bd7-872a-f328df1b7096"
}
}
customer_new
customer_new
When a customer_reference
is provided in the Hosted Checkout request, a customer_new
webhook containing the customer_id
will be provided when a payment request is made.
{
"webhook_type": "customer_new",
"webhook_id": "3e22ae7a-3d4d-47d7-99d0-67ecb3db781c",
"timestamp": 1684254231,
"webhook_body": {
"transaction_id": "",
"status": "success",
"order_id": "J97C6572ddt223-952",
"customer_id": "0dbc3d71-4015-d9f6-633e-9b8290986927"
}
}
card_new
card_new
When a customer's card details used in the Hosted Checkout are saved, the card_new
webhook will be sent containing the card_id
. Card IDs are only created if the payment request is successful.
{
"webhook_type": "card_new",
"webhook_id": "d68a7a29-47ce-43ea-bad3-0e4a35c5f09c",
"timestamp": 1684254231,
"webhook_body": {
"transaction_id": "0e789cf6-7e7a-3c55-870c-e69325975134",
"status": "success",
"order_id": "J97C6572ddt223-952",
"card_id": "77e595b6-686b-724b-6340-6c8ee0123778"
}
}
Webhook retry policy
We consider a webhook as having been successfully delivered when we receive a HTTP status code 200 from your webhook URI.
If we do not receive a 200 success status response code then we will start retrying. Our retry logic will resend the notification every 5 minutes until a 200 status code is returned. If we do not receive a 200 status code after 25 minutes, we will discard the webhook.
Configuring webhooks
Webhooks can be configured from within the Hub, you select the webhook events that are required and define the URL(s) that are to be targeted.
- Firstly, go to Settings menu and from the Company tab select Developers.
- Open the Webhooks tab.
- Select + Add Endpoint and enter the URL to be targeted when sending webhook notifications.
- From the drop-down list select the events that you want to trigger the notifications. (You can select multiple at a time). If you select
status_update
the statuses returned are displayed here.
Note
For Hosted Checkout set up, please refer to the relevant guides.
Managing webhooks
Edit and disable webhooks
You can edit or disable your existing webhooks by clicking into the ellipsis and selecting either option. Once you have confirmed the action, the required amendments will be made.

Viewing webhooks
A list of all attempted webhooks is displayed in the Developer tab in the Webhook Logs section. All details of the webhook can be analysed when clicking into the detail. You also have the option to manually resend the webhook from within the action column or from within the webhook detail.
Note
As with other aspects of the Hub, you can also export your filtered or unfiltered data by running the export button.
Updated about 1 hour ago