Events

API Versioning

Changes to the API result in a new version, following the semantic versioning scheme: MAJOR.MINOR.

MAJOR: Increased when incompatible changes are made public.
MINOR: Increased when the API is extended by new features without breaking the existing API, or when API-compatible bug fixes are applied.

Our goal is to ensure that API changes do not break backward compatibility, striving to keep all consumers running smoothly.

It’s important to note that event messages remain unchanged once created. Subsequent updates to the API (new versions) do not alter existing event messages. Fetching older events using a newer API version also has no impact on the structure of the events. Therefore, older events can be read with a newer API version seamlessly.

This approach maintains consistency and reliability in API usage, allowing for smooth transitions between versions while ensuring backward compatibility. If you have any questions or need further clarification on API versioning, our team is available to provide support and guidance. We’re committed to ensuring a seamless experience for all API consumers.

Delivery and Retries

The Qenta Embedded Finance Platform attempts to deliver your events for up to three days, employing an exponential back-off strategy.

In case of missed events or to reconcile data over a specific period, you can utilize the Event resource.

It’s important to note that events are not rescheduled or retried if no Webhook resource is configured for the event type and is active during creation time.

A successful delivery is considered when:

Your webhook endpoint responds with a 2xx HTTP status code.
The response is received within 3 seconds.

By adhering to these guidelines, you can effectively manage event delivery and ensure timely processing of data. If you have any questions or need further assistance with event delivery and retries, our team is available to provide support and guidance. We’re committed to ensuring the reliability and efficiency of your event processing workflows.

Handle Duplicates

When working with event-driven architectures, it’s important to account for the possibility of receiving duplicate events. To ensure robustness in your event processing logic, consider implementing the following strategies:

Idempotent Processing: Design your event processing logic to be idempotent, meaning that processing the same event multiple times has the same effect as processing it once. This can be achieved by assigning unique identifiers to each event and checking whether an event with the same identifier has already been processed.
Deduplication: Maintain a record of processed events and use it to filter out duplicate events before processing. This can be done by storing event identifiers in a database or using an in-memory cache.
Sequence Number Checking: If events are delivered with sequence numbers or timestamps, use them to detect and discard duplicate events based on their order or arrival time.
Time Window Deduplication: Set a time window within which duplicate events are expected to occur and discard duplicates that fall within this window. This approach is useful when events may be delayed or reordered during transmission.

By implementing these strategies, you can ensure that your event processing system can handle duplicate events effectively, maintaining data integrity and consistency. If you have any questions or need further assistance with handling duplicate events, our team is available to provide support and guidance. We’re committed to helping you build resilient and reliable event-driven applications.

Order of Events

It’s important to note that we do not guarantee the delivery of events in the order in which they are generated. However, if you ensure that no events are missed, you will receive events in the order they were generated.

In case your webhook endpoint does not meet the requirements for successful delivery, we postpone delivery by scheduling a retry with an exponential back-off time. The maximum back-off time is set to 60 minutes. It’s essential to understand that we do not stop sending events during this time, ensuring that event delivery is resilient and continuous.

By acknowledging these aspects of event delivery, you can design your system to handle events effectively and maintain the desired order of processing. If you have any questions or need further clarification on event delivery, our team is available to provide support and guidance. We’re committed to ensuring the reliability and consistency of your event-driven workflows.

Security

To ensure security, an HTTPS endpoint for your webhooks must be provided. We validate the connection to your server, ensuring it’s correctly set up with a valid server certificate. We require at least TLS v1.2 for encryption to guarantee secure data transmission.

Furthermore, only events originating from our IP addresses should be trusted, enhancing the security of event transmission and minimizing the risk of unauthorized access.

By adhering to these security measures, you can safeguard the integrity and confidentiality of your data exchange with the Qenta Embedded Finance Platform. If you have any questions or need further assistance with ensuring the security of your webhook endpoint, our team is available to provide support and guidance. We’re committed to protecting your data and maintaining a secure environment for your operations.

Signature

To validate the content of each request, you’ll need to follow these steps:

Retrieve the signature from the HTTP header with the key X-QENTA-SIG.
The signature value has the format xq:timestamp:hash.
1. Example: X-QENTA-SIG=xq:1632827162:17325e0ae016d1af8006bc6c2c86394c468e39031762a3c221f90e4b1ddf3dfa
Extract the timestamp and hash from the signature.
Calculate the hash by taking the request body and appending the timestamp as it is.
Hash this string using the HmacSHA256 algorithm.
Convert the resulting hash to lowercase for comparison.
Compare the calculated hash with the hash extracted from the signature. For each request, we create a signature based on the shared secret of your webhook. The signature is found in the HTTP header with key X-QENTA-SIG. The value has the following format: xq:timestamp:hash.

Pseudo-code to generate the hash

String timestamp = "1632827162"
String beforeHash = requestBody + timestamp;
String hash = hmacSha256Digest(beforeHash, sharedSecret);

Event Object

Qenta sends you an object with a list of events. The basic object structure of an event is as follows:

{
  "events": [
    {
      "id": "${event_id}",
      "eventType": "${event_type}",
      "apiVersion": "1.0",
      "paymentProgramId": "${payment_program_id},
      "createdAt": "2021-09-28T11:06:02Z",
      "sendingAttemptCount": 2,
      "lastSendingAttemptAt": "2021-09-28T11:10:02Z",
      "data": {
      }
    }
  ]
}

The data field holds the details about the event.

On the first delivery attempt, sendingAttemptCount will be set to zero and lastSendingAttemptAt will be null.

Types of Events

Here are the types of events sent by Qenta, along with the corresponding payload objects:

transaction.authorization: This event occurs when a transaction is authorized. The data payload holds a Transaction object.
transaction.authorization_reversal: This event occurs when a previously authorized transaction is reversed. The data payload holds a Transaction object.
transaction.capture: This event occurs when a transaction is captured. The data payload holds a Transaction object.
transaction.capture_reversal: This event occurs when a previously captured transaction is reversed. The data payload holds a Transaction object.
account.adjustment: This event occurs when an adjustment is made to an account. The data payload holds an AccountAdjustment object.
legal_entity.legal_entity.created: This event occurs when the verification of a legal entity is completed. The data payload holds a LegalEntityVerificationResult object.
legal_entity.verification_result: This event occurs when the verification of a legal entity is completed. The data payload holds a LegalEntityVerificationResult object.

For detailed information about the payloads and their object structures, you can refer to the provided API documentation.