---
title: "Register webhook URLs"
method: POST
path: "/webhook/v3/webhookUrls"
tags: ["Webhook Service"]
---

# Register webhook URLs

`POST /webhook/v3/webhookUrls`

**New webhook workflow**

Registers webhooks for a specific merchant ID or payout account ID. These webhooks are callbacks for transactions, payouts, or spendbacks. 

- Each webhook for a merchant ID receives the same information for all transaction events. 
- Each webhook for a payout account ID receives the same information for all payout and spendback events.

You can create multiple webhooks for the same merchant ID or payout account ID. This is useful for situations where you have multiple workflows from a single event, such as when you need to send the information to two different internal departments but they need to do different things with the same information.

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, you must use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).

<!-- theme: warning -->
> 🛑 Important 
> 
> Nexio supports only either the legacy webhooks or these new ones. Before configuring URLs for your webhooks, ensure that you do not have any URLs for legacy ones configured: [View legacy merchant webhook configuration](https://docs.nexiopay.com/reference/viewmerchantwebhookconfiguration).


<div style="display:none;">

## Request parameters
- merchantId
- webhookUrls 
- payoutAccountId
- accountId

## Response parameters
- merchantId
- payoutAccountId
- accountId
- webhookUrls
- dateCreated
- dateLastModified

</div>

## Next steps
* 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](https://ip-ranges.nex.io/ip-ranges.json).
* [Retrieve a list of webhook URLs](https://docs.nexiopay.com/reference/viewwebhookurlsbyidandtype) that are registered for a merchant ID or payout account ID.
* For a tutorial on how to register and use webhooks, see [Webhooks](https://docs.nexiopay.com/docs/webhooks) in Guides.

For the legacy method for creating webhooks, see the [Create legacy merchant webhooks](https://docs.nexiopay.com/reference/createmerchantwebhooks) endpoint.

## Request body

- union
  - object
    - `merchantId` MerchantId, required — unresolved $ref
    - `webhookUrls` string[], required — An array of all the webhooks to configure for the specified merchant ID, payout account ID, or account ID. The array submitted overwrites any existing array values. **Important:** You must include any existing webhooks in this array, or they will be replaced. To get a list of existing webhooks, see the [View webhook URLs by ID and type](https://docs.nexiopay.com/reference/viewwebhookurlsbyidandtype) endpoint. To remove all webhook URLs, send the request with an empty array.
  - object
    - `payoutAccountId` PayoutAccountId, required — unresolved $ref
    - `webhookUrls` WebhookUrls, required — unresolved $ref
  - object
    - `accountId` string, required — Your Nexio account number. You can get this value from the response for the [Who am I](https://docs.nexiopay.com/reference/whoami) endpoint.
    - `webhookUrls` WebhookUrls, required — unresolved $ref

## Response `200`

Success

- object — f
  - `merchantId` string — The Nexio merchant ID associated with the webhooks. This parameter is only returned when the request included the `merchantId` in the `id` path parameter. Either this parameter, `payoutAccountId`, or `accountId` is returned.c
  - `payoutAccountId` string — The Nexio ID for the payout account associated with the webhooks. This parameter is only returned when the request included the `payoutAccountId` in the `id` path parameter. Either this parameter, `merchantId`, or `accountId` is returned.
  - `accountId` string — The reseller's Nexio account ID associated with the webhooks. This parameter is only returned when the request included the `accountId` in the `id` path parameter. Either this parameter, `merchantId`, or `payoutAccountId` is returned.
  - `webhookUrls` string[] — An array of all the webhooks configured for the specified merchant ID, payout account ID, or reseller account ID.
  - `dateCreated` string — The date and time the configuration was created, formatted as an [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC.
  - `dateLastModified` string — The date and time the configuration was last modified, formatted as an [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC.

## Other responses

- `401` — Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) · [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)