You can subscribe to receive webhooks (notifications) that are sent by ConnectPay. Currently, webhooks are being sent only for payment event types, more event types will be added in the near future.

1. Authorize to receive webhooks
   More details here

2. Subscribe to receive webhooks
   More details here

3. Webhooks information
   More details here

General Webhook Usage Rules

To ensure the optimal performance and reliability of our webhook solution, we have established a set of general rules for using our webhook service. This document outlines these rules and provides guidance on how to effectively handle webhook notifications in your web application, including handling multiple event types.

At Least Once Delivery

Description: Our webhook system is designed to deliver each notification to your endpoint at least once. In certain circumstances, such as network issues or temporary failures, multiple attempts may be made to deliver the notification.

Why it is important:

• Ensures data consistency

• Enhances reliability

How does it affect you:

• Implement idempotent processing

Out of Order Notifications

Due to the nature of distributed systems and network communication, webhook notifications may occasionally arrive out of order. To help you determine the correct sequence of events, we provide a timestamp in the header of each notification (x-connectpay-timestamp).

Why it is important:

• Maintains data integrity

• Allows proper event processing

How does it affect you:

• Use provided timestamps: Utilize the x-connectpay-timestamp header value to determine the correct order of received webhook notifications. Sort the notifications based on their timestamps before processing them in your application.

• Timestamp is in UTC0

Handling Multiple Event Types

Our webhook system supports various event types, each representing a different action or occurrence within our system. All notifications are sent to a single client endpoint, and the specific event type determines the structure of the data included in the request body.

Why it is important:

• Enables event-specific processing

• Provides flexibility

How does it affect you:

• Utilize the "x-connectpay-eventtype" header: The "x-connectpay-eventtype" header value indicates the type of action or event that occurred. Use this header value to identify the appropriate processing logic for each notification, based on the event type.

• Parse and validate data based on event type: For each event type, ensure that your application correctly parses and validates the data in the request body according to the expected structure.

Functional Webhook Headers

Our webhook solution utilizes several custom headers to provide essential information and functionality for each webhook notification.

"x-connectpay-timestamp"

The "x-connectpay-timestamp" header represents the time at which the corresponding action or event occurred. This header contains a timestamp in the ISO-8601 format (YYYY-MM-DDTHH:mm:ss.sssZ UTC0).

Usage:

• Ordering notifications: Use the "x-connectpay-timestamp" header value to determine the correct order of received webhook notifications and process them accordingly.

• Time-sensitive processing: Leverage the timestamp to perform time-sensitive actions or calculations in your application based on when the event occurred.

"x-connectpay-notificationid"

The "x-connectpay-notificationid" header contains a unique identifier for each webhook notification. This identifier can be used to track individual notifications and ensure idempotent processing.

Usage:

• Tracking notifications: Utilize the "x-connectpay-notificationid" header value to track the processing status of each webhook notification in your application logs or database.

• Idempotent processing: Check for duplicate webhook events based on their unique identifiers to ensure that your application processes each event only once, preventing unintended side effects.

"x-connectpay-eventtype"

The "x-connectpay-eventtype" header indicates the type of action or event that occurred and determines the structure of the data included in the request body. This header value helps your application identify the appropriate processing logic for each notification.

Usage:

• Event-specific processing: Use the "x-connectpay-eventtype" header value to route webhook notifications to the appropriate processing functions or handlers within your application, based on the event type.

• Data parsing and validation: Leverage the event type information to correctly parse and validate the data in the request body according to the expected structure for each event type.

"x-connectpay-token"

The "x-connectpay-token" header is used for endpoint authorization, containing the Secret Token that verifies the authenticity and integrity of the webhook notification.

Usage:

• Authentication and integrity: When a webhook notification is received, check that the "x-connectpay-token" header value matches the expected Secret Token to confirm that the request is coming from an authorized source and the data has not been tampered with.

Authorize to receive webhooks

Security

your webhook solution can greatly enhance the protection of your web application. By ensuring only authorized sources can send requests and verifying the integrity of the data, you can reduce the risk of unauthorized access and maintain a secure environment for your application.

IP Whitelisting

IP Whitelisting is a security mechanism that allows you to specify a list of trusted IP addresses or IP ranges from which your web application will accept incoming webhook requests. This helps to protect your application from unauthorized access and malicious traffic.

How to use IP Whitelisting:

1. Identify the IP addresses or IP ranges of the services or systems that will send webhook requests to your application.

2. Configure your application or firewall to accept incoming requests only from the whitelisted IP addresses or IP ranges.

3. Regularly review and update the IP whitelist to ensure that only trusted sources are allowed access.

ConnectPay IP list

Stage

52.31.71.221/32
54.74.228.210/32

Production

34.254.62.56/32
54.195.165.25/32
52.31.241.30/32
54.75.225.162/32
46.137.64.9/32
54.171.90.128/32

Secret Tokens

A Secret Token is a unique, random string that is added to the header of webhook requests to authenticate and verify the source of the request. The token should be kept secret and only known by your application and the sender of the webhook requests.

How to use Secret Tokens:

1. Receive a strong, unique token which is generated by using a secure random number generator.
   Secret Token properties:

   1. The key is 36 characters.

   2. The key may contain uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), and the following special characters: !, #, $, %, &, ', *, +, -, ., ^, _, `, |, ~

2. Configure your application to expect the token in the header of incoming webhook requests. When a request is received, verify that the token in the header matches the expected value.

3. Rotate the token periodically to reduce the risk of compromise.
   This can be done by contacting our support dev-support@connectpay.com.

4. Never share Secret Token value in plain text:

   1. put file with token value into password protected archive. Share password via different communication channel agreed by email communication.

   2. Encrypt file using PGP. ConnectPay’s public key for encryption can be found here: https://dev.connectpay.com/api-portal/sites/default/files/cp/cp-public-pgp-key.asc

   3. Use any other safe method for sensitive data exchange

Header:
x-connectpay-token: <secret token>

Example:
x-connectpay-token: 510b67a3!cd#e543(-caae90a0cf425bc32c

Subscribe to receive webhooks

Subscription procedure

This document outlines the step-by-step procedure to register for our webhooks and configure the required parameters, including the endpoint for receiving notifications.

Step 1: Registration. Please begin by writing email to our support dev-support@connectpay.com. You'll need to provide the following information:

• If you are ConnectPay customer - your legal entity name

• If you are technical partner of ConnectPay customer - legal entity name of ConnectPay customer that you represent.

• The webhook endpoint URL

Upon submitting the registration form, our team will review your request and contact you to confirm your eligibility for using our webhooks.

Step 2: Once your registration is approved, you'll receive a confirmation email with the necessary information required to setup your webhook endpoint. The endpoint is the URL to which our system will send webhook notifications.

Please ensure that your endpoint meets the following requirements:

• Utilizes HTTPS for secure communication

• Is publicly accessible and can receive incoming requests from our IP addresses or IP ranges

• Has implemented the necessary security measures, such as IP Whitelisting and Secret Tokens, as outlined in our security documentation

Please configure your application to expect the Secret Token in the header of incoming webhook requests and ensure that the token is stored securely on your end.

Step 3: Your webhook integration is now complete. We will activate the webhooks for your account, and you'll start receiving notifications at the specified endpoint.

We appreciate your interest in our webhook solution and look forward to providing you with a seamless integration experience. If you have any questions or require further assistance during the onboarding process, please don't hesitate to reach out to our support team at dev-support@connectpay.com.

Webhooks information

General Information

Below is a list of event types we currently send through webhooks. We are planning to add more event types in the near future.

Examples of webhooks with above mentioned event types can be checked here: ConnectPay APIs

Order of events

ConnectPay does not guarantee delivery of webhooks in the order in which they are generated. For example, creating a payment order generates the following webhooks:

• OutgoingPayment.Created

• OutgoingPayment.Processing

• OutgoingPayment.Completed

Your endpoint shouldn’t expect delivery of these webhooks in this order and should handle this accordingly.

Response Status Codes

Your endpoint must return a response status code (2xx) and “OK” in the response body (case insensitive) prior to any complex logic that could cause a timeout.

Built-in retries

ConnectPay webhooks have built-in retry method, which starts, if we do not receive a response status code (2xx) and “OK” in the response body after 10 seconds. Webhook notification is retried 6 times. After 6th retry, if retry is unsuccessful, we stop sending the notification.