Webhook integration

Response Status code

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. Please check response example below.

HTTP/1.1 200 OK
Content-Type: text

OK

After receiving 100 incorrect responses, ConnectPay services will stop sending webhooks.

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 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 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 [email protected].
4. Never share Secret Token value in plain text:
   1. Put the file with the token value into the 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.
   3. Use any other safe method for sensitive data exchange

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

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