Webhook Notifications

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:

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.

Webhook detail

This section provides detailed information on each webhook within the Acquired.com system.

status_update

The status_update webhook provides the merchant with the current status of the payment request.

{
    "webhook_type": "status_update",
    "webhook_id": "298467ac-1f5e-4fad-bc5d-5874bd841df3",
    "webhook_body": {
        "transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
        "status": "cancelled",
        "timestamp": 32908394083,
        "order_id": "6234ae00-1352-4bd7-872a-f328df1b7096"
    }
}

customer_new

If a customer_reference is provided during the initial payment attempt in Hosted Checkout, the merchant will receive the customer_new webhook containing the customer_id.

{
  "webhook_type": "customer_new",
  "webhook_id": "43D25856-18CD-6170-617B-74EAC2A43328",
  "webhook_body": {
    "transaction_id": "",
    "status": "success",
    "timestamp": 1684254231,
    "order_id": "J97C6572ddt223-952",
    "customer_id": "0dbc3d71-4015-d9f6-633e-9b8290986927"
  }
}

card_new

The card_new webhook will only be sent to the merchant if the payment is successfully made through Hosted Checkout.

{
  "webhook_type": "card_new",
  "webhook_id": "2A4EBCEB-8AD8-4CEA-5404-418BAB2CAA8A",
  "webhook_body": {
    "transaction_id": "0e789cf6-7e7a-3c55-870c-e69325975134",
    "status": "success",
    "timestamp": 1684254231,
    "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.

1. Firstly, go to Settings menu and from the Company tab select Webhooks.
2. Enter the URL to be targeted when sending webhook notifications.
3. 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 and Pay by Bank set up, please refer to the relevant guides.

Managing webhooks

Edit and delete webhooks

You can edit or delete 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 Requests menu in the Webhooks tab. 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.