The datahub uses a webhook for notifying certain events occurring to our cardholder customers, such as when a purchase transaction is authorized.

The webhook enables the user to create or set up interactions from event notifications. When one of those is triggered, we will send a POST HTTP request to the set URL. This is a good option because webhooks send event notifications to your endpoint URL, instead of forcing the issuer to search for information in an API.


Applications for using an event webhook in the datahub

Issuers can use the event webhook for building dashboards, metrics, predictive analysis, push, SMS or any similar application.

🚧

Attention

We don’t recommend using this option for data persistency, building repositories as a datalake or in critical applications.


Webhook flow in the datahub

1 – Choose the event you want to receive;
2 – Create the webhook by associating the event with the URL to receive event data from.


Events covered by a webhook in the datahub

The events are divided into:

Account: Created when a new account is generated.
To get to know the details and event fields, use the link: Account.

Person: Created when a natural or legal person is registered or changed in our database.
To get to know the details and event fields, use the link: Person.

Document: Created when a document is associated with any person.
To get to know the details and event fields, use the link: Document.

Phone number: Created when there is any change in the phone number database.
To get to know the details and event fields, use the link: Phone number.

Address: Created when there is any change in our address database.
To get to know the details and event fields, use the link: Address.

Adjustment: Created when a financial adjustment (credit or debit) is made to a cardholder’s account, thus impacting on the balance of the account.
To get to know the details and event fields, use the link: Adjustment.

Card: Created when there is a change in the cards, from creating and blocking a card to sending it for embossing.
To get to know the details and event fields, use the link: Card.

Balance: Created when a balance is changed or associated with any account.
To get to know the details and event fields, use the link: Balance.

Embossing: Sent when an embossing file is generated.
To get to know the details and event fields, use the link: Embossing.

Fee: Created when a fee is registered in the system.
To get to know the details and event fields, use the link: Fee.

Changed Status for a Transaction: Created when there is a change in any status.
To get to know the details and event fields, use the link: Changed Status.

Purchase – Status Created: They are purchase authorizations. When a purchase is authorized, it will trigger this event.
To get to know the details and event fields, use the link: Purchase Created.

Purchase – Status Denied: Purchase transactions denied by the authorizer. That is, when the authorizer denies a transaction, it will trigger this event.
To get to know the details and event fields, use the link: Purchase Denied.

Travel Notice: Created when a travel notice is set up.
To get to know the details and event fields, use the link: Travel Notice.


How an event webhook works

All events are captured within the Dock ecosystem, which is kept in continuous transmission. An API communication layer is available for users to set it as they want to receive these events, which, after being captured, are encrypted and sent, thus providing more security. Events are delivered through webhooks, that is, the HTTP request is sent to any provided URL and managed by the issuer.

📘

Note

In case there is any change that might impact on the event format, whether a field or its content, the issuer will be notified.


Getting started with an event webhook in the datahub

To get started, you will need to contact your sales account manager in order to proceed with the contracting process, while also checking steps required for setting it up. These are:

Authentication: In order to register webhooks in our platform, you need to identify and ensure to take action for the correct issuers. That’s why you need to have a certificate previously signed by a certifying agent or a request for signing the certificate.

Cryptography: In order to ensure more security for information in transit between applications, the entire payload for the event is encrypted. To that end, you need to share your keys. That’s why the issuer needs to have a previously generated RSA key pair.

Events: The webhook is a flexible application, so you can choose the events that can be sent to issuers. Thus, it has more control over the issuer’s business and will not incur unnecessary costs with underutilized events. That’s why the issuer needs to have a list of the events they want to receive.

For details on the steps you need to take for setting it up, use the link: Setup.


Registering webhooks

After the aforementioned steps, you can register webhook by using two options:

Curl: To understand how to use it in details, go to: Curl.
Postman: To understand how to use it in details, go to: Postman.


Testing webhooks

Sandbox

You can get to know an event’s capabilities and understand potential steps to be taken when getting started with a productive environment.

Independently of setup and influence from third-parties, you can receive events containing fictional data in the production, testing and developing address with a structure that is identical to the one receiving it in a production environment.

• In order to better understand how webhook tests work, go to: Test webhooks.


Registering test webhooks

• In order to register test webhooks, use the endpoint: Register webhook.


Using event webhooks in the datahub

• In order to update webhooks registered in the API, use the endpoint: Change webhook.

• In order to list all webhooks registered, use the endpoint: List webhooks.

• In order to find an event webhook, use the endpoint: Find webbook.


Retries

After the initial setup, events will start being captured, but they will be discarded until a webhook is registered to receive them.

After registering it, events will be sent to the created URL. It is crucial for the issuer’s API to be able to receive large volumes of requests and to respond by using HTTP codes that are semantically correct. This is extremely relevant because the webhook will use that response to send the event to the right target.

In addition to delivering events, a webhook has functionalities that aim to reduce circumstances where these events are lost in the last integration layer—integrating with the issuer’s API. One of those functionalities involves retries with exponential delay.

When does a retry occur?

When invoking HTTP to the issuer’s API, a webhook expects to receive a valid HTTP code in response, thus interpretating what happened with the delivered event. The webhook doesn’t use any other response apart from the HTTP code.

Retries with exponential delay

This functionality ensures up to 10 retries to send an event before discarding it. It means that a webhook will wait up to 4 hours and 30 minutes approximately for the issuer’s API to be up and running again before discarding the event. See below a table showing samples of number of retries by using the waiting time limit for each one.

Retry

Waiting time (s)

Time for retry

1

32

01:50:01 pm

2

64

01:51:05 pm

3

128

01:53:13 pm

4

256

01:57:29 pm

5

512

02:06:01 pm

6

1024

02:23:05 pm

7

2048

02:57:13 pm

8

4096

04:05:29 pm

9

8192

06:22:01 pm

10

16384

10:55:05 pm

📘

Note

After all retries, the event is discarded, and you won’t be able re-send it.

Identifying the current retry

Any event that is sent to the customer has headers storing important metadata for the event delivery and capturing flow.

As events are re-sent, the header DataHubMessageDeliveryCount is incremented, and you can use it to identify the retry occurring at a specific moment.

We emphasize that the retry flow doesn’t block the normal flow for sending events. They are kept for later retries, while other events keep being sent. If the issuer’s application successfully starts responding to requests again, you are likely to receive the more recent event first and older events later, which are in the retry flow.


Did this page help you?