Skip to main content

Overview

Introduction​

Webhooks allow the Merchant to track events happening in Paysafe Embedded wallet. The following object changes can be tracked using webhooks.

It is the Merchant's responsibility to:

  • expose API endpoints for webhook handling
  • configure the webhook root URL with Paysafe
  • ensure the availability of the endpoints to receive the webhooks

Request format​

Webhooks are sent to your configured URLs as HTTP POST requests with a JSON body. Use HTTPS for your webhook endpoint URLs. Respond with HTTP 2xx (for example, 200) as soon as you have accepted the payload; process the event asynchronously if needed so that your endpoint responds within a reasonable time and avoids timeouts or retries.

Getting started​

In order to start receiving notifications the URL for each event type should be configured. As well as http statuses that need to trigger the retry mechanism described below.

All notifications can be signed before sending using HMAC. In order to turn on HMAC signing, the secret, used for signing, should be communicated and set. More about HMAC signing you can find in the section Webhook signature below.

Supported events​

The Webhooks service supports multiple types of events related to various aspects of customer's activity:

  • Accounts - The webhook is sent when there's an update on the customer account. The operationType signifies the change that occurred.
  • Customer restrictions - Events related to any changes in restriction status of a customer. Contain information about restriction name, restriction reason and required actions.
  • Kyc verifications - Know Your Customer verification status updates for customers.
  • Payment Instruments - Events related to all changes in payment instruments of a customer.
  • Transactions - This webhook will be sent when the status of all transaction types is updated - deposit, withdrawal or transfers.
  • Prepaid cards - Events related to prepaid card updates.
    • Card status updates - This webhook will be sent when the card status is updated
    • Card tokenization events - This webhook will be sent when the card is tokenized by Google, Apple or a merchant website.
    • Card token updates - This webhook will be sent when the card token is updated. A token update event occurs when the token associated with a card is updated due to changes in card details or security updates, ensuring seamless and secure transactions by automatically replacing the old token with a new one across platforms like Google Pay, Apple Pay, and merchant websites.
    • Card 3ds challenge events - This webhook will be sent when card 3ds authentication process is initiated.
    • Card bulk order events - This webhook will be sent upon the completion of the card bulk order process.
  • SCA Authentication - This webhook is triggered when an SCA authentication process is needed to finalize a wallet operation.
  • Customer Data Verification - This webhook will be sent when a customer data verification process has been successfully initiated.
  • Credentials Change - This webhook will be sent when change of the customer credentials has occurred. It contains the type of the credentials change, customer information and customer identifiers (e.g. email, mobile, etc.).

Retry mechanism​

If an event is not successfully delivered to your endpoint, the webhooks service retries the delivery.

  • When retries happen: Retries are triggered at the event-sending step when your endpoint returns an error, does not respond in time, or returns an HTTP status that is configured to trigger retries.
  • Retry policy: The service supports ongoing retries with a configurable timeout.
  • Configurable HTTP statuses: Which HTTP response statuses trigger a retry can be configured when setting up webhooks (for example, retries on 5xx but not on 4xx).
  • Stopping retries: Return a successful HTTP response (for example, 2xx) from your webhook endpoint to acknowledge receipt and avoid further retries. Implement idempotent handling so that duplicate deliveries (e.g. after a retry) are safe.
  • Event ordering: Events may arrive out of order or more than once across the system. Events are ordered per wallet (customer) or per transaction, so you can rely on ordering within that scope. Your webhook handler should process events in an idempotent way and use event identifiers or timestamps if you need to enforce ordering or detect duplicates.

Error scenarios​

In case of any error during the event processing, the event is stored in the system.

For any error during sending the event, the event is retried according to the retry mechanism. If retry is not configured the event is stored in the system.

Webhook Signature​

The webhook notification contains a signature header calculated using the following algorithm:

  • digest = HMAC_SHA256 (hmacKey, UTF 8 string containing the JSON webhook request body)
  • signature = base 64 encode (digest)

The code receiving the webhook needs to repeat this algorithm and compare the value generated with the value received in the header.

Example Header:

Signature: UMaQ4h635wUc4hp60Z5ASBC/5UtqKybAldOkLv6ngc0=

For more details on request signing please check the Request Signing documentation.

Notifications Resend API (in development)​

In cases some issue in the merchant system prevented proper event processing, events can be replayed using Notification Resend API. In order to use this feature you need to specify searching criteria to filter events, then notifications will be sent to the URLs one more time. Pay attention that events are stored in the system for one month, so the older ones could not be available for resend.

Notification Resend API allows the Merchant to request the re-sending of events that have already been sent and delivered successfully to the Merchant.