Configuring legacy webhooks

🚧

Important

Nexio supports only either the new webhooks or these legacy ones. Before configuring legacy webhook URLs, ensure that you do not have any new ones configured: View webhook URLs by ID and type.

To configure webhooks for a merchant, follow the steps below:

1. Check Your Merchant's Role (Optional)

   In order to configure webhooks for a merchant, you must have administrator or write access to that merchant account.
   If you know that your user has sufficient rights, skip to step 2.

   To check your account's access rights, send a request to the Who am I endpoint
   in the User Management Service.

   In the example below, the user has authorization to configure webhooks for merchant ID 100039 only.

   Example Access Rights

   {
     "accessRights": {
       "merchantIds": {
         "100039": "A", // Admin access
         "100040": "W", // Write access
         "100068": "R" // Read-only access
       },
       "role": "A"
     }
   }
   

2. Determine the Event Types

   See the Event types table and note the event types you would like to trigger a webhook.

3. Post Configuration Information to Nexio

   Send a POST request to the Create legacy merchant webhooks endpoint.
   Include the merchant ID, the event type(s) you selected in step 2, and the endpoint to which the data will be sent.

   The example below configures a webhook to be sent to https://your-ecommerce-website.example.com when a transaction is authorized or refunded for merchant ID 100039.

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]'
     -d '{
     "merchantId": "100039",
     "webhooks": {
       "TRANSACTION_AUTHORIZED": {
         "url": "https://your-ecommerce-website.example.com"
       },
       "TRANSACTION_REFUNDED": {
         "url": "https://your-ecommerce-website.example.com"
       }
     }
   }'
   

4. If needed, whitelist the IP addresses that send the webhooks. You can find the list for both sandbox and production environments at https://ip-ranges.nex.io/ip-ranges.json. Note: The list is dynamic and is updated periodically. Therefore, you should re-check it periodically.

5. Check the Webhook's Configuration (Optional)

   To check the webhook configuration you completed in step 4, send a GET request to the View legacy merchant webhook configuration endpoint.

   Example Request

   curl -X GET https://api.nexiopaysandbox.com/webhook/v3/config/100039 \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]'
   

   
   
   Example 200 Response

   {
     "dateCreated": "2019-03-22T16:58:51.957Z",
     "webhooks": {
       "TRANSACTION_AUTHORIZED": {
         "url": "https://your-company-webhook-url-here.com"
       },
       "TRANSACTION_CAPTURED": {
         "url": "https://your-company-webhook-url-here.com"
       }
     },
     "merchantName": "My Company",
     "dateLastModified": "2019-04-04T18:54:58.011Z",
     "merchantId": "100039"
   }
   

   
   

6. Configure the Webhook Secret (Optional)

   For additional security, you may set up a webhook secret.
   After the secret is configured, you will be provided with a secret and each webhook will include a header containing a signature.
   Use these to verify that all data received is authentic.

   To configure the secret, send a POST request to the Create a webhook secret endpoint.
   Include the merchant ID or payout account ID to be configured in the body of your request.

   Example Request for Merchant Secret

   curl -X POST https://api.nexiopaysandbox.com/webhook/v3/secret \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]'
     -d '{
     "merchantId": "100039"
   }'
   

   A successful request returns a response object containing the secret. Store the secret in a secure location. You will use it later for signature verification (see step 3).

   Example Webhook Secret

   {
     "secret": "446946d5-bdd9-48c7-9504-0459d19c08e5"
   }
   

After you have configured the secret, each webhook includes a signature header (see step 3).

See Also

• Deregistering legacy webhooks