Registering webhooks

You can register webhooks for a merchant ID or payout account ID, or Nexio account ID.

🚧

Important

Nexio supports only either the legacy webhooks or these new ones. Before configuring your webhook URLs, ensure that you do not have any legacy ones configured: View legacy merchant webhook configuration.

To configure webhooks for a merchant ID or payout account ID, or Nexio account ID, follow the steps below:

1. Determine whether you want to add a webhook for transactions (through the merchant ID) or for payouts (through the payout account ID), or for merchant applications (for the reseller through the Nexio account ID).
   Note: You can create webhooks in the sandbox environment for merchant applications, however, the system will never send a webhook for account events because the onboarding application process only works in the production environment.
   

2. If needed, check your access rights for the merchant ID or payout account ID.

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

   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 and payout account ID 3927.

   Example Access Rights

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

📘

Try it out . . .

1. Go to the Who am I endpoint.

2. Type your username and password in the Authentication section.

3. Click the Try it! button.

   The response should include lots of parameters, including the objects and parameters in the example above.

   If you get anything other than a 200 Response, check that you provided a valid username and password. If that does not help, contact us for more assistance.

3. If needed, get a list of existing webhooks by sending a GET request to the View webhook URLs by ID and type endpoint.

   The following examples request the webhooks for a specified merchant ID (100039) or a specified payout account ID (3927), and a specified Nexio account ID (27592004).

   merchantIdpayoutAccountId

   curl --request GET \
     --url https://api.nexiopaysandbox.com/webhook/v3/webhookUrls/100039/MERCHANT \
     --header 'Authorization: Basic [Base64_encoded_login]' \
     --header 'Content-Type: application/json'
   

   curl --request GET \
     --url https://api.nexiopaysandbox.com/webhook/v3/webhookUrls/3927/PAYOUT_ACCOUNT \
     --header 'Authorization: Basic [Base64_encoded_login]' \
     --header 'Content-Type: application/json'
   

   
   The response lists any configured webhook URLs in a webhookUrls array.
   

   merchantIdResponsepayoutAccountIdResponse

   {
     "dateCreated": "2022-01-14T16:46:56.393Z",
     "dateLastModified": "2022-03-24T21:55:02.998Z",
     "webhookUrls": [
       "https://your-ecommerce-website.example.com?webhook12345",
       "https://webhook.site/ca1002e9-1f52-4733-a1a4-db05e93f7064"
     ],
     "merchantId": "100039"
   }
   

   {
     "dateCreated": "2022-03-24T21:36:03.375Z",
     "dateLastModified": "2022-03-24T21:36:03.375Z",
     "webhookUrls": [
       "https://webhook.site/1d255420-876e-43ba-b2d6-640101c505ad"
     ],
     "payoutAccountId": "3927"
   }
   

   
   

   📘

   Try it out . . .

   1. Go to the View webhook URLs by ID and type endpoint.

   2. Type a value for the id that is a merchant ID, payout account ID, or Nexio account ID.

   3. Type a value for the webhook_type that is MERCHANT or PAYOUT_ACCOUNT or ACCOUNT, depending on the ID you use.

   4. Type your username and password in the Authentication section.

   5. Click the Try it! button.

      The response should include lots of parameters, including the objects and parameters in the example above.

      If you get anything other than a 200 Response, check that you provided a valid username and password. If that does not help, contact us for more assistance.

   If the webhookUrls array contains any values, copy any that you want to keep and use them in the next step.
   
   

4. Send a POST request to the Register webhook URLs endpoint.

   Include a merchant ID or payout account ID, or Nexio account ID and the webhook URLs you want to register. If you are adding to existing URLs, you also need the existing registered ones (see step 3).

   The example below configures a second webhook for merchant ID 100039 to be sent to https://your-ecommerce-website.example.com/123abc when a transaction status changes.

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/webhook/v3/webhookUrls \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]'
     -d '{
     "merchantId": "100039",
     "webhookUrls": [
       "https://your-ecommerce-website.example.com/123abc",
       "https://webhook.site/ca1002e9-1f52-4733-a1a4-db05e93f7064"
     ]
   }'
   

   
   

   This returns a response similar to the following:

   Example Request

   {
     "dateLastModified": "2022-03-25T21:42:41.528Z",
     "dateCreated": "2022-01-14T16:46:56.393Z",
     "webhookUrls": [
       "https://your-ecommerce-website.example.com/123abc",
       "https://webhook.site/ca1002e9-1f52-4733-a1a4-db05e93f7064"
     ],
     "merchantId": "100039"
   }
   

   
   

   📘

   Try it out . . .

   1. Go to the Register webhook URLs endpoint.

   2. Type your username and password in the Authentication section.

   3. Type a value for the merchantId or payoutAccountId, or the accountId.

   4. Type one or more webhook URLs (click ADD STRING to add a second and subsequent URLs). Make sure to include any existing URLs that are registered, unless you want to delete them.

   5. Click the Try it! button.

      The response should include lots of parameters, including the objects and parameters in the example above.

      If you get anything other than a 200 Response, check that you provided a valid username and password. If that does not help, contact us for more assistance.

   
   

5. 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.

See also

• Receiving webhooks - Provides a tutorial for receiving the webhooks you have registered.
• Webhook body examples - Presents example webhook example responses.