Skip to main content

​
Overview

You can subscribe to specific event types to receive real-time event notifications. This enables you to build efficient, event-driven workflows and respond promptly to changes in transaction activity, account status, and other critical events.

​
How event notifications work

When an event occurs, Imprint will POST to the endpoint configured. This event notification contains a JSON payload with details about the event. As part of event notification enrollment, you will receive a secret shared only between Imprint and you.All requests are signed (HMAC SHA-256) using the shared secret. For increased security, you can restrict your endpoint to only allow requests from Imprint’s IP Ranges, which can be provided by your Imprint team. Your system should acknowledge events with a 2XX HTTP response status to confirm successful receipt. If a delivery fails, Imprint will retry the request based on an exponential back-off strategy.

​
Setup

To start receiving event notifications, please coordinate the following with your Imprint team:
  1. Select events: subscribe to specific event types. For a description of each event notification, see the reference pages.
  2. Register your endpoint(s): provide at least one publicly accessible URL where events should be sent. You may provide multiple endpoints, e.g. one per event type. All endpoints must use HTTPS to ensure encrypted communication.
  3. Store event signing token: your Imprint team will provide the secret key that you will use to validate the signature of incoming requests. Please see the signature verification page for more detail on how to interpret the X-IMPRINT-HMAC-SIGNATURE header.
  4. Retry logic: implement idempotency handling to avoid processing duplicate events, as Imprint will retry failed webhook deliveries.

​
Handle duplicate events

You may receive duplicate event notifications occasionally due to network issues or retry logic. To ensure your system processes each event only once, implement idempotency handling by tracking which events have already been processed. You can uniquely identify events using a combination of:
  • object (e.g., TRANSACTION, APPLICATION)
  • id (e.g., transaction_id, event_id, payment_method_id)
  • updated_at timestamp in the event data payload
We recommend storing these identifiers when processing an event and checking against them before processing subsequent events. If you receive an event with matching identifiers, you can safely ignore it as a duplicate.

​
Examples

​
Transaction notifications

Below, we have provided more detail regarding the possible transaction statuses and expected transaction scenarios.

​
Transaction statuses

Use transaction_id to track a transaction throughout the lifecycle of different statuses and event_id to identify each step uniquely

​
Common transaction scenarios

1

Customer completes $50 purchase

As soon as the customer pays with their card, you will receive an APPROVED event. However, it may take several hours for the merchant to finalize the transaction through the card network. Once a transaction is finalized, you will receive a CAPTURED event with the confirmed purchase amount.
In some cases, merchants may bypass the APPROVED step (e.g., force capture) or capture for more/less than the APPROVED amount. Regardless, CAPTURED always represents a confirmed purchase amount.
2

Customer completes $50 purchase, which is partially captured multiple times

It’s possible for a merchant to capture a single transaction multiple times (e.g., single order split into multiple shipments). When this happens, you will receive multiple CAPTURED events with the amount encompassing each individual charge.
3

Merchant updates transaction amount

It’s possible for merchants to authorize one amount initially and later request an updated authorization amount that is higher/lower. For example, automated fuel dispensers which authorize for ~$100 immediately and then update the authorization to the final purchase amount after the customer has finished pumping.
4

Merchant cancels the order

If a merchant reverses an APPROVED authorization or lets the authorization expire (e.g., after nine days without capture), you will receive a VOIDED event.
5

Customer completes $50 purchase, then receives a $30 refund

There can be multiple refunds associated with a transaction and you will receive a REFUNDED event for each. In most cases, refunds are linked to an existing transaction (e.g., example below), but standalone refunds are possible as well.
6

$50 purchase is disputed and won by the customer

If the CAPTURED transaction is disputed and won by the customer (e.g., example below), it translates to a new refund. If the dispute is lost, no change - it’s still a purchase on the customer’s statement.