Webhooks (also called web callbacks or HTTP push API) allow an application to provide its consumers with near real-time information related to the occurrence of different events.

Unlike other systems where one needs to constantly query for the desired data or results, webhooks will send these updates to the interested consumer the moment a change of interest occurs.

For a consumer, receiving notifications via webhooks translates practically into the ability to get the near real-time information about their transactions of interest or tokens and for a sender into the ability to publish that information to interested subscribers as close as possible to the moment of their occurrence.

Webhooks are also referred to as “Reverse APIs”, as opposed to standard APIs where you make a call to a system, it is them that receives a call from the system. The webhook will make HTTP requests to the merchant's application with transaction or token related information.

Events

By using the webhooks service, merchants can be notified of the events triggered by AceHub according to their preferences.

Events are categorized in types and subtypes, allowing merchants to subscribe to all events filtered by a specific type and/or subtype.

In AceHub, all webhook events belong to the following event type:

Type
Description
Transaction
Events related to AceHub transactions.
Tokenization
Events related to Tokens.

For the Transaction event type, AceHub defines the following event subtypes:

Subtype
Description
Create
Triggered when a new transaction is created.
Update
Triggered when an existing transaction changes its status.

For the Tokenization event type, we define the following event subtypes:

Subtype
Description
Create
Triggered when a new token is created.
Update
Triggered when an existing token changes its status.

Webhooks allow merchants to subscribe to one or more types of events, so when an event of a certain type is produced in AceHub, webhooks will notify all the subscribers of that event.

Creating webhooks

In order to use the AceHub webhooks service the merchant needs to create a webhooks listener. This will be an HTTP endpoint listening to event notifications.

Merchants can define a webhook where they subscribe their endpoints to listen to the events of their choice. Each webhook is configured with the following elements:

  • The endpoint URL of the webhook listener.
  • (optional) A secondary endpoint URL, in case the primary one is not available.
  • The type and subtype of the event the webhook will be subscribed to.

How do webhooks work?

When an event occurs, a notification message is triggered according to the following policy:

  1. The webhook sends the message to the primary listener URL.
  2. If the listener URL does not respond with a 2XX HTTP code, the message will be sent to the secondary listener URL (if it exists).
  3. If both listener URLs fail, the webhook will retry sending the message with a delay. The higher the number of retries, the longer the delay.
  4. If the listener continues failing after a number of retries, it will be quarantined and the merchant will be notified.

Setting up webhooks

Once you have created your webhook listener(s), kindly contact our Technical Support team to set up webhooks for your account.

During the setup process, our notification server sends a test message to the registered URL with a payload in the following format.

{
  "Id":"6cabaa30-2364-91ba-3052-553b57a6f524",
  "Type":"Health",
  "CreateTime":"2019-07-22T10:04:53.155203Z",
  "Message":"Test message",
  "EventTime":"2019-07-22T10:04:53.145203Z",
  "Payload":null
}

This test message has to be acknowledged by your listener URL with a HTTP 2XX response.

This tests that...

  • Your listener URL is correct
  • Your network setup accepts our webhook notification server
  • Your listener URL can receive our messages
  • Your listener URL responds in the expected format

When this test is successful, your listener URL will start to receive the actual notifications for the subscribed events.

Webhooks message structure

Information about the webhooks message format can be found in the webhooks message reference.

Updated 6 months ago

Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Top