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.CreatedOutgoingPayment.ProcessingOutgoingPayment.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 200 http response code and text OK in the response body (case insensitive). We recommend to respond back to us, prior to performing any complex logic that could cause a timeout.
Built-in retries
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.
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. Each retry happens after the specified times:
1) After 5 seconds.
2) After 5 more seconds.
3) After 30 seconds.
4) After 5 minutes.
5) After 60 minutes.
6) After 24 hours.
After 100 webhook are failed to send the notification service is turned off. Webhooks can be turned on again by contacting support team: [email protected].
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.